@vellumai/assistant 0.4.26 → 0.4.29

package/src/tasks/task-runner.ts

@@ -1,12 +1,15 @@
-import { createConversation } from '../memory/conversation-store.js';
-import { GENERATING_TITLE, queueGenerateConversationTitle } from '../memory/conversation-title-service.js';
-import { invalidateAssistantInferredItemsForConversation } from '../memory/task-memory-cleanup.js';
-import { getLogger } from '../util/logger.js';
-import { buildTaskRules, clearTaskRunRules,setTaskRunRules } from './ephemeral-permissions.js';
-import { createTaskRun, getTask, updateTaskRun } from './task-store.js';
-import { sanitizeToolList } from './tool-sanitizer.js';
-
-const log = getLogger('task-runner');
+import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
+import { invalidateAssistantInferredItemsForConversation } from "../memory/task-memory-cleanup.js";
+import { getLogger } from "../util/logger.js";
+import {
+  buildTaskRules,
+  clearTaskRunRules,
+  setTaskRunRules,
+} from "./ephemeral-permissions.js";
+import { createTaskRun, getTask, updateTaskRun } from "./task-store.js";
+import { sanitizeToolList } from "./tool-sanitizer.js";
+
+const log = getLogger("task-runner");
 
 export interface TaskRunOptions {
   taskId: string;
@@ -21,12 +24,15 @@ export interface TaskRunOptions {
 export interface TaskRunResult {
   taskRunId: string;
   conversationId: string;
-  status: 'completed' | 'failed';
+  status: "completed" | "failed";
   error?: string;
 }
 
 /** Replace {{key}} placeholders in template with values from inputs. */
-export function renderTemplate(template: string, inputs: Record<string, string>): string {
+export function renderTemplate(
+  template: string,
+  inputs: Record<string, string>,
+): string {
   return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
     if (key in inputs) return inputs[key];
     return `<MISSING: ${key}>`;
@@ -39,7 +45,11 @@ export function renderTemplate(template: string, inputs: Record<string, string>)
  */
 export async function runTask(
   opts: TaskRunOptions,
-  processMessage: (conversationId: string, message: string, taskRunId: string) => Promise<void>,
+  processMessage: (
+    conversationId: string,
+    message: string,
+    taskRunId: string,
+  ) => Promise<void>,
 ): Promise<TaskRunResult> {
   const task = getTask(opts.taskId);
   if (!task) {
@@ -47,10 +57,11 @@ export async function runTask(
   }
 
   const run = createTaskRun(task.id);
-  const conversation = createConversation({ title: GENERATING_TITLE, threadType: 'background', source: opts.source });
-  queueGenerateConversationTitle({
-    conversationId: conversation.id,
-    context: { origin: 'task', systemHint: `Task: ${task.title}` },
+  const conversation = bootstrapConversation({
+    threadType: "background",
+    source: opts.source,
+    origin: "task",
+    systemHint: `Task: ${task.title}`,
   });
 
   updateTaskRun(run.id, {
@@ -60,42 +71,59 @@ export async function runTask(
 
   // Build and register ephemeral permission rules. If the user pre-approved
   // specific tools via the preflight flow, use those instead of all requiredTools.
-  const requiredTools = sanitizeToolList(task.requiredTools ? JSON.parse(task.requiredTools) : []);
-  const toolsForRules = opts.approvedTools ? sanitizeToolList(opts.approvedTools) : requiredTools;
+  const requiredTools = sanitizeToolList(
+    task.requiredTools ? JSON.parse(task.requiredTools) : [],
+  );
+  const toolsForRules = opts.approvedTools
+    ? sanitizeToolList(opts.approvedTools)
+    : requiredTools;
   const rules = buildTaskRules(run.id, toolsForRules, opts.workingDir);
   setTaskRunRules(run.id, rules);
 
   try {
     const renderedTemplate = renderTemplate(task.template, opts.inputs ?? {});
 
-    updateTaskRun(run.id, { status: 'running', startedAt: Date.now() });
+    updateTaskRun(run.id, { status: "running", startedAt: Date.now() });
 
-    log.info({ taskId: task.id, taskRunId: run.id, conversationId: conversation.id }, 'Executing task');
+    log.info(
+      { taskId: task.id, taskRunId: run.id, conversationId: conversation.id },
+      "Executing task",
+    );
     await processMessage(conversation.id, renderedTemplate, run.id);
 
-    updateTaskRun(run.id, { status: 'completed', finishedAt: Date.now() });
+    updateTaskRun(run.id, { status: "completed", finishedAt: Date.now() });
 
     return {
       taskRunId: run.id,
       conversationId: conversation.id,
-      status: 'completed',
+      status: "completed",
     };
   } catch (err) {
     const errorMessage = err instanceof Error ? err.message : String(err);
-    log.warn({ err, taskId: task.id, taskRunId: run.id }, 'Task execution failed');
+    log.warn(
+      { err, taskId: task.id, taskRunId: run.id },
+      "Task execution failed",
+    );
 
-    updateTaskRun(run.id, { status: 'failed', error: errorMessage, finishedAt: Date.now() });
+    updateTaskRun(run.id, {
+      status: "failed",
+      error: errorMessage,
+      finishedAt: Date.now(),
+    });
 
     try {
       invalidateAssistantInferredItemsForConversation(conversation.id);
     } catch (cleanupErr) {
-      log.warn({ err: cleanupErr, conversationId: conversation.id }, 'Failed to invalidate assistant-inferred memory items');
+      log.warn(
+        { err: cleanupErr, conversationId: conversation.id },
+        "Failed to invalidate assistant-inferred memory items",
+      );
     }
 
     return {
       taskRunId: run.id,
       conversationId: conversation.id,
-      status: 'failed',
+      status: "failed",
       error: errorMessage,
     };
   } finally {

package/src/tasks/task-scheduler.ts

@@ -1,4 +1,4 @@
-import { createSchedule } from '../schedule/schedule-store.js';
+import { createSchedule } from "../schedule/schedule-store.js";
 
 /**
  * Create a cron schedule that runs a task on a recurring cron expression.

package/src/tasks/task-store.ts

@@ -1,7 +1,7 @@
-import { desc, eq, inArray } from 'drizzle-orm';
+import { desc, eq, inArray } from "drizzle-orm";
 
-import { getDb } from '../memory/db.js';
-import { taskRuns, tasks, workItems } from '../memory/schema.js';
+import { getDb } from "../memory/db.js";
+import { taskRuns, tasks, workItems } from "../memory/schema.js";
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -50,9 +50,11 @@ export function createTask(opts: {
     template: opts.template,
     inputSchema: opts.inputSchema ? JSON.stringify(opts.inputSchema) : null,
     contextFlags: opts.contextFlags ? JSON.stringify(opts.contextFlags) : null,
-    requiredTools: opts.requiredTools ? JSON.stringify(opts.requiredTools) : null,
+    requiredTools: opts.requiredTools
+      ? JSON.stringify(opts.requiredTools)
+      : null,
     createdFromConversationId: opts.createdFromConversationId ?? null,
-    status: 'active',
+    status: "active",
     createdAt: now,
     updatedAt: now,
   };
@@ -102,7 +104,7 @@ export function createTaskRun(taskId: string): TaskRun {
     id,
     taskId,
     conversationId: null,
-    status: 'pending',
+    status: "pending",
     startedAt: null,
     finishedAt: null,
     error: null,
@@ -116,7 +118,18 @@ export function createTaskRun(taskId: string): TaskRun {
 
 export function updateTaskRun(
   id: string,
-  updates: Partial<Pick<TaskRun, 'status' | 'conversationId' | 'error' | 'principalId' | 'memoryScopeId' | 'startedAt' | 'finishedAt'>>,
+  updates: Partial<
+    Pick<
+      TaskRun,
+      | "status"
+      | "conversationId"
+      | "error"
+      | "principalId"
+      | "memoryScopeId"
+      | "startedAt"
+      | "finishedAt"
+    >
+  >,
 ): void {
   const db = getDb();
   db.update(taskRuns).set(updates).where(eq(taskRuns.id, id)).run();

package/src/tasks/tool-sanitizer.ts

@@ -1,4 +1,4 @@
-import { getAllTools,getTool } from '../tools/registry.js';
+import { getAllTools, getTool } from "../tools/registry.js";
 
 /**
  * Deduplicate and sort a list of tool names, validating against the live
@@ -11,7 +11,7 @@ export function sanitizeToolList(tools: string[]): string[] {
   const seen = new Set<string>();
 
   for (const tool of tools) {
-    if (!tool || typeof tool !== 'string') continue;
+    if (!tool || typeof tool !== "string") continue;
     seen.add(tool);
   }
 
@@ -24,7 +24,7 @@ export function sanitizeToolList(tools: string[]): string[] {
  */
 export function getRegisteredToolNames(): string[] {
   return getAllTools()
-    .filter((t) => t.executionMode !== 'proxy' && t.origin !== 'skill')
+    .filter((t) => t.executionMode !== "proxy" && t.origin !== "skill")
     .map((t) => t.name)
     .sort();
 }

package/src/tools/apps/definitions.ts

@@ -8,16 +8,18 @@
  * executor scripts.
  */
 
-import { RiskLevel } from '../../permissions/types.js';
-import type { ToolDefinition } from '../../providers/types.js';
-import type { Tool, ToolExecutionResult } from '../types.js';
+import { RiskLevel } from "../../permissions/types.js";
+import type { ToolDefinition } from "../../providers/types.js";
+import type { Tool, ToolExecutionResult } from "../types.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 function proxyExecute(): Promise<ToolExecutionResult> {
-  throw new Error('Proxy tool: execution must be forwarded to the connected client');
+  throw new Error(
+    "Proxy tool: execution must be forwarded to the connected client",
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -25,31 +27,37 @@ function proxyExecute(): Promise<ToolExecutionResult> {
 // ---------------------------------------------------------------------------
 
 const appOpenTool: Tool = {
-  name: 'app_open',
+  name: "app_open",
   description:
-    'Open a persistent app in a dynamic_page surface on the connected client.',
-  category: 'apps',
+    "Open a persistent app in a dynamic_page surface on the connected client.",
+  category: "apps",
   defaultRiskLevel: RiskLevel.Low,
-  executionMode: 'proxy',
+  executionMode: "proxy",
 
   getDefinition(): ToolDefinition {
     return {
       name: this.name,
       description: this.description,
       input_schema: {
-        type: 'object',
+        type: "object",
         properties: {
           app_id: {
-            type: 'string',
-            description: 'The ID of the app to open',
+            type: "string",
+            description: "The ID of the app to open",
           },
           open_mode: {
-            type: 'string',
-            enum: ['preview', 'workspace'],
-            description: "Display mode. 'preview' shows an inline preview card in chat. 'workspace' opens the full app in a workspace panel. Defaults to 'workspace'.",
+            type: "string",
+            enum: ["preview", "workspace"],
+            description:
+              "Display mode. 'preview' shows an inline preview card in chat. 'workspace' opens the full app in a workspace panel. Defaults to 'workspace'.",
+          },
+          reason: {
+            type: "string",
+            description:
+              "Brief non-technical explanation of what you are opening and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
           },
         },
-        required: ['app_id'],
+        required: ["app_id"],
       },
     };
   },

package/src/tools/apps/executors.ts

@@ -8,9 +8,9 @@
  * ToolDefinition or ToolContext types.
  */
 
-import { setHomeBaseAppLink } from '../../home-base/app-link-store.js';
-import type { AppDefinition } from '../../memory/app-store.js';
-import type { EditEngineResult } from '../../memory/app-store.js';
+import { setHomeBaseAppLink } from "../../home-base/app-link-store.js";
+import type { AppDefinition } from "../../memory/app-store.js";
+import type { EditEngineResult } from "../../memory/app-store.js";
 
 // ---------------------------------------------------------------------------
 // Shared result type
@@ -43,11 +43,16 @@ export interface AppStoreWriter {
     schemaJson: string;
     htmlDefinition: string;
     pages?: Record<string, string>;
-    appType?: 'app' | 'site';
+    appType?: "app" | "site";
   }): AppDefinition;
   updateApp(
     id: string,
-    updates: Partial<Pick<AppDefinition, 'name' | 'description' | 'schemaJson' | 'htmlDefinition' | 'pages'>>,
+    updates: Partial<
+      Pick<
+        AppDefinition,
+        "name" | "description" | "schemaJson" | "htmlDefinition" | "pages"
+      >
+    >,
   ): AppDefinition;
   deleteApp(id: string): void;
   writeAppFile(appId: string, path: string, content: string): void;
@@ -81,7 +86,7 @@ export interface AppCreateInput {
   schema_json?: string;
   html: string;
   pages?: Record<string, string>;
-  type?: 'app' | 'site';
+  type?: "app" | "site";
   auto_open?: boolean;
   set_as_home_base?: boolean;
   preview?: Record<string, unknown>;
@@ -94,55 +99,97 @@ export async function executeAppCreate(
 ): Promise<ExecutorResult> {
   const name = input.name;
   const description = input.description;
-  const schemaJson = input.schema_json ?? '{}';
+  const schemaJson = input.schema_json ?? "{}";
   const htmlDefinition = input.html;
   const pages = input.pages;
   const autoOpen = input.auto_open !== false; // default true
   const preview = input.preview;
-  const appType = input.type === 'site' ? 'site' as const : 'app' as const;
+  const appType = input.type === "site" ? ("site" as const) : ("app" as const);
 
   // Validate required fields — LLM input is not type-checked at runtime
-  if (typeof name !== 'string' || name.trim() === '') {
-    return { content: JSON.stringify({ error: 'name is required and must be a non-empty string' }), isError: true };
+  if (typeof name !== "string" || name.trim() === "") {
+    return {
+      content: JSON.stringify({
+        error: "name is required and must be a non-empty string",
+      }),
+      isError: true,
+    };
   }
-  if (typeof htmlDefinition !== 'string') {
-    return { content: JSON.stringify({ error: 'html is required and must be a string containing the HTML definition' }), isError: true };
+  if (typeof htmlDefinition !== "string") {
+    return {
+      content: JSON.stringify({
+        error:
+          "html is required and must be a string containing the HTML definition",
+      }),
+      isError: true,
+    };
   }
   if (pages) {
     for (const [filename, content] of Object.entries(pages)) {
-      if (typeof content !== 'string') {
-        return { content: JSON.stringify({ error: `pages["${filename}"] must be a string, got ${typeof content}` }), isError: true };
+      if (typeof content !== "string") {
+        return {
+          content: JSON.stringify({
+            error: `pages["${filename}"] must be a string, got ${typeof content}`,
+          }),
+          isError: true,
+        };
       }
     }
   }
 
-  const app = store.createApp({ name, description, schemaJson, htmlDefinition, pages, appType });
+  const app = store.createApp({
+    name,
+    description,
+    schemaJson,
+    htmlDefinition,
+    pages,
+    appType,
+  });
 
   if (input.set_as_home_base) {
-    setHomeBaseAppLink(app.id, 'personalized');
+    setHomeBaseAppLink(app.id, "personalized");
   }
 
   // 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) {
-    const createPreview = { ...(preview ?? {}), context: 'app_create' as const };
-    const extraInput = { preview: createPreview, open_mode: 'preview' };
+    const createPreview = {
+      ...(preview ?? {}),
+      context: "app_create" as const,
+    };
+    const extraInput = { preview: createPreview, open_mode: "preview" };
     try {
-      const openResult = await proxyToolResolver('app_open', { app_id: app.id, ...extraInput });
+      const openResult = await proxyToolResolver("app_open", {
+        app_id: app.id,
+        ...extraInput,
+      });
       if (openResult.isError) {
         return {
-          content: JSON.stringify({ ...app, auto_opened: false, auto_open_error: openResult.content }),
+          content: JSON.stringify({
+            ...app,
+            auto_opened: false,
+            auto_open_error: openResult.content,
+          }),
           isError: false,
         };
       }
       return {
-        content: JSON.stringify({ ...app, auto_opened: true, open_result: openResult.content }),
+        content: JSON.stringify({
+          ...app,
+          auto_opened: true,
+          open_result: openResult.content,
+        }),
         isError: false,
       };
     } catch {
       // Preview emission failure is non-fatal — the app was created successfully.
       return {
-        content: JSON.stringify({ ...app, auto_opened: false, auto_open_error: 'Failed to auto-open app. Use app_open to open it manually.' }),
+        content: JSON.stringify({
+          ...app,
+          auto_opened: false,
+          auto_open_error:
+            "Failed to auto-open app. Use app_open to open it manually.",
+        }),
         isError: false,
       };
     }
@@ -198,12 +245,20 @@ export function executeAppUpdate(
   input: AppUpdateInput,
   store: AppStore,
 ): ExecutorResult {
-  const updates: Partial<Pick<AppDefinition, 'name' | 'description' | 'schemaJson' | 'htmlDefinition' | 'pages'>> = {};
-  if (typeof input.name === 'string') updates.name = input.name;
-  if (typeof input.description === 'string') updates.description = input.description;
-  if (typeof input.schema_json === 'string') updates.schemaJson = input.schema_json;
-  if (typeof input.html === 'string') updates.htmlDefinition = input.html;
-  if (input.pages && typeof input.pages === 'object') updates.pages = input.pages;
+  const updates: Partial<
+    Pick<
+      AppDefinition,
+      "name" | "description" | "schemaJson" | "htmlDefinition" | "pages"
+    >
+  > = {};
+  if (typeof input.name === "string") updates.name = input.name;
+  if (typeof input.description === "string")
+    updates.description = input.description;
+  if (typeof input.schema_json === "string")
+    updates.schemaJson = input.schema_json;
+  if (typeof input.html === "string") updates.htmlDefinition = input.html;
+  if (input.pages && typeof input.pages === "object")
+    updates.pages = input.pages;
 
   const app = store.updateApp(input.app_id, updates);
   return { content: JSON.stringify(app), isError: false };
@@ -222,7 +277,10 @@ export function executeAppDelete(
   store: AppStore,
 ): ExecutorResult {
   store.deleteApp(input.app_id);
-  return { content: JSON.stringify({ deleted: true, appId: input.app_id }), isError: false };
+  return {
+    content: JSON.stringify({ deleted: true, appId: input.app_id }),
+    isError: false,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -260,16 +318,19 @@ export function executeAppFileRead(
   const limit = input.limit;
 
   const raw = store.readAppFile(input.app_id, input.path);
-  const allLines = raw.split('\n');
+  const allLines = raw.split("\n");
   const startIndex = Math.max(0, offset - 1);
-  const sliced = limit != null ? allLines.slice(startIndex, startIndex + limit) : allLines.slice(startIndex);
+  const sliced =
+    limit != null
+      ? allLines.slice(startIndex, startIndex + limit)
+      : allLines.slice(startIndex);
 
   const formatted = sliced
     .map((line, i) => {
       const lineNum = startIndex + i + 1;
       return `${String(lineNum).padStart(6)}\t${line}`;
     })
-    .join('\n');
+    .join("\n");
 
   return { content: formatted, isError: false };
 }
@@ -292,12 +353,25 @@ export function executeAppFileEdit(
   store: AppStore,
 ): ExecutorResult {
   if (!input.old_string) {
-    return { content: JSON.stringify({ error: 'old_string must not be empty' }), isError: true };
+    return {
+      content: JSON.stringify({ error: "old_string must not be empty" }),
+      isError: true,
+    };
   }
 
   const replaceAll = input.replace_all ?? false;
-  const result = store.editAppFile(input.app_id, input.path, input.old_string, input.new_string, replaceAll);
-  return { content: JSON.stringify(result), isError: false, status: input.status };
+  const result = store.editAppFile(
+    input.app_id,
+    input.path,
+    input.old_string,
+    input.new_string,
+    replaceAll,
+  );
+  return {
+    content: JSON.stringify(result),
+    isError: false,
+    status: input.status,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -317,9 +391,16 @@ export function executeAppFileWrite(
 ): ExecutorResult {
   const app = store.getApp(input.app_id);
   if (!app) {
-    return { content: JSON.stringify({ error: `App '${input.app_id}' not found` }), isError: true };
+    return {
+      content: JSON.stringify({ error: `App '${input.app_id}' not found` }),
+      isError: true,
+    };
   }
 
   store.writeAppFile(input.app_id, input.path, input.content);
-  return { content: JSON.stringify({ written: true, path: input.path }), isError: false, status: input.status };
+  return {
+    content: JSON.stringify({ written: true, path: input.path }),
+    isError: false,
+    status: input.status,
+  };
 }

package/src/tools/apps/open-proxy.ts

@@ -6,7 +6,7 @@
  * a single implementation with consistent success/failure messaging.
  */
 
-import type { ExecutorResult,ProxyResolver } from './executors.js';
+import type { ExecutorResult, ProxyResolver } from "./executors.js";
 
 /**
  * Open an app on the connected client via the proxy tool resolver.
@@ -25,19 +25,19 @@ export async function openAppViaSurface(
   extraInput?: Record<string, unknown>,
 ): Promise<string> {
   if (!proxyToolResolver) {
-    return 'App created but could not be opened (no connected client). Use app_open to open it manually.';
+    return "App created but could not be opened (no connected client). Use app_open to open it manually.";
   }
 
   try {
-    const result: ExecutorResult = await proxyToolResolver('app_open', {
+    const result: ExecutorResult = await proxyToolResolver("app_open", {
       app_id: appId,
       ...extraInput,
     });
     if (result.isError) {
-      return 'Failed to auto-open app. Use app_open to open it manually.';
+      return "Failed to auto-open app. Use app_open to open it manually.";
     }
     return result.content;
   } catch {
-    return 'Failed to auto-open app. Use app_open to open it manually.';
+    return "Failed to auto-open app. Use app_open to open it manually.";
   }
 }

package/src/tools/apps/registry.ts

@@ -6,8 +6,8 @@
  * provided by the app-builder skill via its TOOLS.json manifest.
  */
 
-import { registerTool } from '../registry.js';
-import { coreAppProxyTools } from './definitions.js';
+import { registerTool } from "../registry.js";
+import { coreAppProxyTools } from "./definitions.js";
 
 export function registerAppTools(): void {
   for (const tool of coreAppProxyTools) {