@vellumai/assistant 0.8.1 → 0.8.3

package/src/tools/apps/executors.ts

@@ -86,6 +86,7 @@ export interface AppCreateInput {
   pages?: unknown;
   auto_open?: boolean;
   preview?: Record<string, unknown>;
+  source_files?: Record<string, string>;
 }
 
 export async function executeAppCreate(
@@ -129,6 +130,31 @@ export async function executeAppCreate(
     };
   }
 
+  if (input.source_files != null) {
+    if (
+      typeof input.source_files !== "object" ||
+      Array.isArray(input.source_files)
+    ) {
+      return {
+        content: JSON.stringify({
+          error:
+            "source_files must be an object mapping relative file paths to string contents",
+        }),
+        isError: true,
+      };
+    }
+    for (const [key, val] of Object.entries(input.source_files)) {
+      if (typeof val !== "string") {
+        return {
+          content: JSON.stringify({
+            error: `source_files["${key}"] must be a string, got ${typeof val}`,
+          }),
+          isError: true,
+        };
+      }
+    }
+  }
+
   // Extract icon from preview if provided - only persist emoji-like values,
   // not URLs which would render as raw strings in UI and bundle manifests.
   const rawIcon = preview?.icon as string | undefined;
@@ -172,17 +198,32 @@ function App() {
 render(<App />, document.getElementById('app')!);
 `;
 
-  // Only write scaffold files when they don't already exist on disk.
-  // The LLM may have written custom source files via file_write before
-  // calling app_create, and overwriting them would destroy the real app
-  // content, leaving only the scaffold placeholder.
+  if (input.source_files) {
+    for (const [filePath, content] of Object.entries(input.source_files)) {
+      store.writeAppFile(app.id, filePath, content);
+    }
+  }
+
+  const mainTsxScaffolded = !store.appFileExists(app.id, "src/main.tsx");
   if (!store.appFileExists(app.id, "src/index.html")) {
     store.writeAppFile(app.id, "src/index.html", indexHtml);
   }
-  if (!store.appFileExists(app.id, "src/main.tsx")) {
+  if (mainTsxScaffolded) {
     store.writeAppFile(app.id, "src/main.tsx", mainTsx);
   }
 
+  // When the placeholder main.tsx was actually scaffolded, the tool result
+  // must steer the agent toward writing the real source files instead of
+  // treating success + inline AppCard as task-done. When the agent pre-wrote
+  // src/main.tsx before calling app_create, this directive would be false
+  // and risks prompting a destructive rewrite, so omit it in that case.
+  const nextStepsField = mainTsxScaffolded
+    ? {
+        next_steps:
+          "Scaffold created with a placeholder src/main.tsx only. The app is NOT built yet. You MUST now (1) write the real src/main.tsx, components under src/components/, and src/styles.css with file_write, then (2) call app_refresh once. Stopping here leaves an empty Hello-world placeholder as the only result.",
+      }
+    : {};
+
   // Compile src/ → dist/
   const appDir = getAppDirPath(app.id);
   const compileResult = await compileApp(appDir);
@@ -193,6 +234,7 @@ render(<App />, document.getElementById('app')!);
         compile_errors: compileResult.errors,
         compile_warnings: compileResult.warnings,
         compile_duration_ms: compileResult.durationMs,
+        ...nextStepsField,
       }),
       isError: false,
     };
@@ -200,7 +242,7 @@ render(<App />, document.getElementById('app')!);
 
   // Emit the inline preview card via the proxy without opening a workspace panel.
   // open_mode: "preview" signals to the client that this should be shown inline only.
-  if (autoOpen && proxyToolResolver) {
+  if (autoOpen && !mainTsxScaffolded && proxyToolResolver) {
     const createPreview = {
       ...(preview ?? {}),
       context: "app_create" as const,
@@ -217,6 +259,7 @@ render(<App />, document.getElementById('app')!);
             ...app,
             auto_opened: false,
             auto_open_error: openResult.content,
+            ...nextStepsField,
           }),
           isError: false,
         };
@@ -226,6 +269,7 @@ render(<App />, document.getElementById('app')!);
           ...app,
           auto_opened: true,
           open_result: openResult.content,
+          ...nextStepsField,
         }),
         isError: false,
       };
@@ -237,13 +281,20 @@ render(<App />, document.getElementById('app')!);
           auto_opened: false,
           auto_open_error:
             "Failed to auto-open app. Use app_open to open it manually.",
+          ...nextStepsField,
         }),
         isError: false,
       };
     }
   }
 
-  return { content: JSON.stringify(app), isError: false };
+  return {
+    content: JSON.stringify({
+      ...app,
+      ...nextStepsField,
+    }),
+    isError: false,
+  };
 }
 
 // ---------------------------------------------------------------------------

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

@@ -0,0 +1,509 @@
+import { describe, expect, test } from "bun:test";
+
+import type { QuestionPromptResult } from "../../permissions/question-prompter.js";
+import type { ToolContext } from "../types.js";
+import { AskQuestionTool } from "./ask-question-tool.js";
+
+type PromptParams = Parameters<
+  import("../../permissions/question-prompter.js").QuestionPrompter["prompt"]
+>[0];
+
+function makeContext(overrides: Partial<ToolContext> = {}): ToolContext {
+  return {
+    workingDir: "/tmp",
+    conversationId: "conv-1",
+    trustClass: "guardian",
+    toolUseId: "tu-1",
+    ...overrides,
+  };
+}
+
+function makeToolWithStub(result: QuestionPromptResult): {
+  tool: AskQuestionTool;
+  calls: PromptParams[];
+} {
+  const calls: PromptParams[] = [];
+  const tool = new AskQuestionTool(() => ({
+    async prompt(params: PromptParams) {
+      calls.push(params);
+      return result;
+    },
+  }));
+  return { tool, calls };
+}
+
+const validInput = {
+  question: "Which fruit?",
+  description: "Pick one to add to the smoothie.",
+  options: [
+    { id: "a", label: "Apple" },
+    { id: "b", label: "Banana", description: "Ripe" },
+  ],
+  freeTextPlaceholder: "Type a fruit",
+};
+
+const singleQ = {
+  question: validInput.question,
+  description: validInput.description,
+  options: validInput.options,
+  freeTextPlaceholder: validInput.freeTextPlaceholder,
+};
+
+describe("AskQuestionTool definition", () => {
+  test("exposes the expected schema shape and description language", () => {
+    const def = new AskQuestionTool().getDefinition();
+    expect(def.name).toBe("ask_question");
+    expect(def.description).toContain("free-text fallback is always added");
+    expect(def.description).toContain("do not");
+    expect(def.description).toContain("'something else'");
+    expect(def.description).toContain("plain-text clarification");
+    expect(def.description).toContain("obvious from context");
+    expect(def.description).toContain("Use this tool whenever");
+    expect(def.description).toContain("When in doubt");
+    expect(def.description).toContain("plausible interpretations");
+    expect(def.description).toContain("remove guessing");
+    expect(def.description).toContain("a question is skipped");
+    expect(def.description).toContain("every question in the batch is skipped");
+    // Batching language is back now that the prompter handles batches.
+    expect(def.description).toContain("Batch related clarifications");
+    expect(def.description).toContain("up to 5");
+    expect(def.description).toContain("Skip button");
+
+    const schema = def.input_schema as {
+      properties: Record<
+        string,
+        { type?: string; minItems?: number; maxItems?: number }
+      >;
+      required?: string[];
+    };
+    expect(schema.properties.options?.type).toBe("array");
+    expect(schema.properties.options?.minItems).toBe(2);
+    expect(schema.properties.options?.maxItems).toBe(4);
+  });
+});
+
+// Build a single-question completed result for tests that just need to
+// exercise the formatter on a one-element batch.
+function singleCompleted(
+  entry:
+    | { decision: "option"; optionId: string }
+    | { decision: "free_text"; text: string }
+    | { decision: "skipped" },
+): QuestionPromptResult {
+  return {
+    entries: [{ questionId: "q1", ...entry }],
+    overall: "completed",
+  };
+}
+
+describe("AskQuestionTool.execute", () => {
+  test("forwards questions array unchanged to the prompter", async () => {
+    const { tool, calls } = makeToolWithStub(
+      singleCompleted({ decision: "option", optionId: "a" }),
+    );
+
+    const result = await tool.execute(validInput, makeContext());
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.conversationId).toBe("conv-1");
+    expect(calls[0]?.questions).toHaveLength(1);
+    expect(calls[0]?.questions[0]?.question).toBe(validInput.question);
+    expect(calls[0]?.questions[0]?.description).toBe(validInput.description);
+    expect(calls[0]?.questions[0]?.options).toEqual(validInput.options);
+    expect(calls[0]?.questions[0]?.freeTextPlaceholder).toBe(
+      validInput.freeTextPlaceholder,
+    );
+    expect(calls[0]?.toolUseId).toBe("tu-1");
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toBe(
+      `Question "${validInput.question}" → Option: a (Apple)`,
+    );
+  });
+
+  test("formats option result with looked-up label", async () => {
+    const { tool } = makeToolWithStub(
+      singleCompleted({ decision: "option", optionId: "b" }),
+    );
+    const result = await tool.execute(validInput, makeContext());
+    expect(result.content).toBe(
+      `Question "${validInput.question}" → Option: b (Banana)`,
+    );
+    expect(result.isError).toBe(false);
+  });
+
+  test("falls back to '(unknown)' label when optionId is not in options", async () => {
+    const { tool } = makeToolWithStub(
+      singleCompleted({ decision: "option", optionId: "ghost" }),
+    );
+    const result = await tool.execute(validInput, makeContext());
+    expect(result.content).toBe(
+      `Question "${validInput.question}" → Option: ghost ((unknown))`,
+    );
+    expect(result.isError).toBe(false);
+  });
+
+  test("formats free-text result", async () => {
+    const { tool } = makeToolWithStub(
+      singleCompleted({ decision: "free_text", text: "Cherry" }),
+    );
+    const result = await tool.execute(validInput, makeContext());
+    expect(result.content).toBe(
+      `Question "${validInput.question}" → Free text: Cherry`,
+    );
+    expect(result.isError).toBe(false);
+  });
+
+  test("formats skipped result", async () => {
+    const { tool } = makeToolWithStub(singleCompleted({ decision: "skipped" }));
+    const result = await tool.execute(validInput, makeContext());
+    expect(result.content).toBe(`Question "${validInput.question}" → Skipped`);
+    expect(result.isError).toBe(false);
+  });
+
+  test("timeout produces tool error", async () => {
+    const { tool } = makeToolWithStub({
+      entries: [{ questionId: "q1", decision: "timed_out" }],
+      overall: "timed_out",
+    });
+    const result = await tool.execute(validInput, makeContext());
+    expect(result.isError).toBe(true);
+    expect(result.content).toBe("User did not respond within timeout");
+  });
+
+  test("aborted produces tool error", async () => {
+    const { tool } = makeToolWithStub({
+      entries: [{ questionId: "q1", decision: "skipped" }],
+      overall: "aborted",
+    });
+    const result = await tool.execute(validInput, makeContext());
+    expect(result.isError).toBe(true);
+    expect(result.content).toBe("Question aborted");
+  });
+
+  test("rejects input with fewer than 2 options", async () => {
+    const { tool, calls } = makeToolWithStub(
+      singleCompleted({ decision: "option", optionId: "a" }),
+    );
+    const result = await tool.execute(
+      { ...validInput, options: [{ id: "a", label: "Apple" }] },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content.toLowerCase()).toContain("invalid input");
+    expect(calls).toHaveLength(0);
+  });
+
+  test("rejects input with more than 4 options", async () => {
+    const { tool, calls } = makeToolWithStub(
+      singleCompleted({ decision: "option", optionId: "a" }),
+    );
+    const result = await tool.execute(
+      {
+        ...validInput,
+        options: [
+          { id: "a", label: "A" },
+          { id: "b", label: "B" },
+          { id: "c", label: "C" },
+          { id: "d", label: "D" },
+          { id: "e", label: "E" },
+        ],
+      },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(calls).toHaveLength(0);
+  });
+
+  test("rejects input with empty question", async () => {
+    const { tool, calls } = makeToolWithStub(
+      singleCompleted({ decision: "option", optionId: "a" }),
+    );
+    const result = await tool.execute(
+      { ...validInput, question: "" },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(calls).toHaveLength(0);
+  });
+
+  test("propagates abort signal into the prompter", async () => {
+    const { tool, calls } = makeToolWithStub(
+      singleCompleted({ decision: "option", optionId: "a" }),
+    );
+    const ac = new AbortController();
+    await tool.execute(validInput, makeContext({ signal: ac.signal }));
+    expect(calls[0]?.signal).toBe(ac.signal);
+  });
+});
+
+// ── Batched input ───────────────────────────────────────────────────
+
+describe("AskQuestionTool batched input", () => {
+  test("normalizes legacy flat input into a one-element batch forwarded to the prompter", async () => {
+    const { tool, calls } = makeToolWithStub(
+      singleCompleted({ decision: "option", optionId: "a" }),
+    );
+
+    const result = await tool.execute(validInput, makeContext());
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.questions).toHaveLength(1);
+    expect(calls[0]?.questions[0]?.question).toBe(validInput.question);
+    expect(calls[0]?.questions[0]?.options).toEqual(validInput.options);
+    expect(result.isError).toBe(false);
+  });
+
+  test("accepts a single-element `questions` batch", async () => {
+    const { tool, calls } = makeToolWithStub(
+      singleCompleted({ decision: "option", optionId: "a" }),
+    );
+
+    const result = await tool.execute({ questions: [singleQ] }, makeContext());
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.questions).toHaveLength(1);
+    expect(calls[0]?.questions[0]?.question).toBe(singleQ.question);
+    expect(calls[0]?.questions[0]?.options).toEqual(singleQ.options);
+    expect(calls[0]?.questions[0]?.description).toBe(singleQ.description);
+    expect(calls[0]?.questions[0]?.freeTextPlaceholder).toBe(
+      singleQ.freeTextPlaceholder,
+    );
+    expect(result.isError).toBe(false);
+  });
+
+  test("forwards the full questions array for a multi-question batch", async () => {
+    const q2 = {
+      question: "Preferred time?",
+      options: [
+        { id: "morning", label: "Morning" },
+        { id: "afternoon", label: "Afternoon" },
+      ],
+      freeTextPlaceholder: "or specify",
+    };
+    const q3 = {
+      question: "Send invite?",
+      options: [
+        { id: "yes", label: "Yes" },
+        { id: "no", label: "No" },
+      ],
+    };
+
+    const { tool, calls } = makeToolWithStub({
+      entries: [
+        { questionId: "q1", decision: "option", optionId: "a" },
+        { questionId: "q2", decision: "free_text", text: "noon-ish" },
+        { questionId: "q3", decision: "option", optionId: "yes" },
+      ],
+      overall: "completed",
+    });
+
+    const result = await tool.execute(
+      { questions: [singleQ, q2, q3] },
+      makeContext(),
+    );
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.questions).toHaveLength(3);
+    expect(calls[0]?.questions.map((q) => q.question)).toEqual([
+      singleQ.question,
+      q2.question,
+      q3.question,
+    ]);
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toBe(
+      [
+        `Question "${singleQ.question}" → Option: a (Apple)`,
+        `Question "${q2.question}" → Free text: noon-ish`,
+        `Question "${q3.question}" → Option: yes (Yes)`,
+      ].join("\n"),
+    );
+  });
+
+  test("formats all-skipped batch as a non-error transcript", async () => {
+    const q2 = {
+      question: "Preferred time?",
+      options: [
+        { id: "morning", label: "Morning" },
+        { id: "afternoon", label: "Afternoon" },
+      ],
+    };
+    const q3 = {
+      question: "Send invite?",
+      options: [
+        { id: "yes", label: "Yes" },
+        { id: "no", label: "No" },
+      ],
+    };
+    const { tool } = makeToolWithStub({
+      entries: [
+        { questionId: "q1", decision: "skipped" },
+        { questionId: "q2", decision: "skipped" },
+        { questionId: "q3", decision: "skipped" },
+      ],
+      overall: "completed",
+    });
+
+    const result = await tool.execute(
+      { questions: [singleQ, q2, q3] },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toBe(
+      [
+        `Question "${singleQ.question}" → Skipped`,
+        `Question "${q2.question}" → Skipped`,
+        `Question "${q3.question}" → Skipped`,
+      ].join("\n"),
+    );
+  });
+
+  test("closed batch prepends a summary line and remains non-error", async () => {
+    const q2 = {
+      question: "Preferred time?",
+      options: [
+        { id: "morning", label: "Morning" },
+        { id: "afternoon", label: "Afternoon" },
+      ],
+    };
+    const { tool } = makeToolWithStub({
+      entries: [
+        { questionId: "q1", decision: "skipped" },
+        { questionId: "q2", decision: "skipped" },
+      ],
+      overall: "closed",
+    });
+
+    const result = await tool.execute(
+      { questions: [singleQ, q2] },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toBe(
+      [
+        "User closed the question card without answering. All questions skipped.",
+        `Question "${singleQ.question}" → Skipped`,
+        `Question "${q2.question}" → Skipped`,
+      ].join("\n"),
+    );
+  });
+
+  test("accepts a 5-entry batch (max allowed)", async () => {
+    const { tool, calls } = makeToolWithStub({
+      entries: [
+        { questionId: "q1", decision: "skipped" },
+        { questionId: "q2", decision: "skipped" },
+        { questionId: "q3", decision: "skipped" },
+        { questionId: "q4", decision: "skipped" },
+        { questionId: "q5", decision: "skipped" },
+      ],
+      overall: "completed",
+    });
+    const five = [singleQ, singleQ, singleQ, singleQ, singleQ];
+
+    const result = await tool.execute({ questions: five }, makeContext());
+
+    expect(result.isError).toBe(false);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.questions).toHaveLength(5);
+  });
+
+  test("rejects batches with 6+ questions", async () => {
+    const { tool, calls } = makeToolWithStub(
+      singleCompleted({ decision: "option", optionId: "a" }),
+    );
+    const six = [singleQ, singleQ, singleQ, singleQ, singleQ, singleQ];
+
+    const result = await tool.execute({ questions: six }, makeContext());
+
+    expect(result.isError).toBe(true);
+    expect(result.content.toLowerCase()).toContain("invalid input");
+    expect(calls).toHaveLength(0);
+  });
+
+  test("rejects empty `questions` array", async () => {
+    const { tool, calls } = makeToolWithStub(
+      singleCompleted({ decision: "option", optionId: "a" }),
+    );
+
+    const result = await tool.execute({ questions: [] }, makeContext());
+
+    expect(result.isError).toBe(true);
+    expect(result.content.toLowerCase()).toContain("invalid input");
+    expect(calls).toHaveLength(0);
+  });
+
+  test("rejects input missing both `questions` and flat fields", async () => {
+    const { tool, calls } = makeToolWithStub(
+      singleCompleted({ decision: "option", optionId: "a" }),
+    );
+
+    const result = await tool.execute({}, makeContext());
+
+    expect(result.isError).toBe(true);
+    expect(result.content.toLowerCase()).toContain("invalid input");
+    expect(calls).toHaveLength(0);
+  });
+
+  test("rejects legacy `question` without `options`", async () => {
+    const { tool, calls } = makeToolWithStub(
+      singleCompleted({ decision: "option", optionId: "a" }),
+    );
+
+    const result = await tool.execute({ question: "Hi?" }, makeContext());
+
+    expect(result.isError).toBe(true);
+    expect(result.content.toLowerCase()).toContain("invalid input");
+    expect(calls).toHaveLength(0);
+  });
+});
+
+describe("AskQuestionTool definition (batched schema)", () => {
+  test("exposes `questions[]` shape, keeps legacy fields, omits per-question id", () => {
+    const def = new AskQuestionTool().getDefinition();
+    const schema = def.input_schema as {
+      properties: Record<
+        string,
+        {
+          type?: string;
+          minItems?: number;
+          maxItems?: number;
+          items?: {
+            type?: string;
+            properties?: Record<string, unknown>;
+            required?: string[];
+          };
+        }
+      >;
+      required?: string[];
+    };
+
+    const questions = schema.properties.questions;
+    expect(questions?.type).toBe("array");
+    expect(questions?.minItems).toBe(1);
+    expect(questions?.maxItems).toBe(5);
+
+    const itemProps = questions?.items?.properties ?? {};
+    expect(Object.keys(itemProps)).toEqual(
+      expect.arrayContaining([
+        "question",
+        "description",
+        "options",
+        "freeTextPlaceholder",
+      ]),
+    );
+    expect(Object.keys(itemProps)).not.toContain("id");
+    expect(questions?.items?.required).toEqual(["question", "options"]);
+
+    expect(schema.properties.question?.type).toBe("string");
+    expect(schema.properties.options?.type).toBe("array");
+    expect(schema.properties.options?.minItems).toBe(2);
+    expect(schema.properties.options?.maxItems).toBe(4);
+    expect(schema.properties.freeTextPlaceholder?.type).toBe("string");
+
+    expect(schema.required).toBeUndefined();
+  });
+});