@vellumai/assistant 0.4.45 → 0.4.48

package/src/tools/host-filesystem/write.ts

@@ -27,13 +27,8 @@ class HostFileWriteTool implements Tool {
             type: "string",
             description: "The content to write to the file",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of why this file is being written, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
-        required: ["path", "content", "reason"],
+        required: ["path", "content"],
       },
     };
   }

package/src/tools/mcp/mcp-tool-factory.ts

@@ -2,6 +2,7 @@ import type { McpServerConfig } from "../../config/schemas/mcp.js";
 import type { McpServerManager } from "../../mcp/manager.js";
 import { RiskLevel } from "../../permissions/types.js";
 import type { ToolDefinition } from "../../providers/types.js";
+import { schemaDefinesProperty } from "../schema-transforms.js";
 import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
 const riskMap: Record<string, RiskLevel> = {
@@ -36,6 +37,10 @@ export function createMcpTool(
 ): Tool {
   const namespacedName = mcpToolName(serverId, metadata.name);
   const riskLevel = riskMap[serverConfig.defaultRiskLevel] ?? RiskLevel.High;
+  const serverDefinesReason = schemaDefinesProperty(
+    metadata.inputSchema,
+    "reason",
+  );
 
   return {
     name: namespacedName,
@@ -59,7 +64,19 @@ export function createMcpTool(
       _context: ToolContext,
     ): Promise<ToolExecutionResult> {
       try {
-        const result = await manager.callTool(serverId, metadata.name, input);
+        // Strip injected reason before sending to MCP server
+        const { reason: _reason, ...mcpInput } = input as Record<
+          string,
+          unknown
+        > & {
+          reason?: unknown;
+        };
+        const forwardInput = serverDefinesReason ? input : mcpInput;
+        const result = await manager.callTool(
+          serverId,
+          metadata.name,
+          forwardInput,
+        );
         return {
           content: result.content,
           isError: result.isError,

package/src/tools/memory/definitions.ts

@@ -62,11 +62,6 @@ const memoryManageProperties = {
     type: "string" as const,
     description: "Short subject/topic label, 2-8 words (optional, save only)",
   },
-  reason: {
-    type: "string" as const,
-    description:
-      "Brief non-technical explanation shown to the user as a status update",
-  },
 };
 
 export const memoryManageDefinition: ToolDefinition = {

package/src/tools/network/web-fetch.ts

@@ -863,11 +863,6 @@ class WebFetchTool implements Tool {
             description:
               "If true, allows requests to localhost/private-network hosts. Disabled by default for SSRF safety.",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are fetching and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
         required: ["url"],
       },

package/src/tools/network/web-search.ts

@@ -302,11 +302,6 @@ class WebSearchTool implements Tool {
             description:
               'Filter by recency: "pd" (past day), "pw" (past week), "pm" (past month), "py" (past year). Only used with Brave provider.',
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are searching for and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
         required: ["query"],
       },

package/src/tools/schema-transforms.ts

@@ -0,0 +1,99 @@
+import type { ToolDefinition } from "../providers/types.js";
+
+/**
+ * Tools that should never have a `reason` field injected into their schema.
+ */
+export const REASON_SKIP_SET = new Set<string>([
+  "skill_execute",
+  "bash",
+  "host_bash",
+  "request_system_permission",
+]);
+
+/**
+ * Injects a `reason` string property into each tool definition's input schema,
+ * unless the tool is in the skip set, already has a reason field, or has a
+ * non-object schema.
+ *
+ * CRITICAL: Never mutates the input definitions — always returns deep clones
+ * for any modified definition, since `getDefinition()` returns shared refs.
+ */
+export function injectReasonField(
+  definitions: ToolDefinition[],
+  skip: Set<string> = REASON_SKIP_SET,
+): ToolDefinition[] {
+  return definitions.map((def) => {
+    if (skip.has(def.name)) {
+      return def;
+    }
+
+    const schema = def.input_schema as Record<string, unknown>;
+    if (schema.type !== "object" || !schema.properties) {
+      return def;
+    }
+
+    const properties = schema.properties as Record<string, unknown>;
+    if (schemaDefinesProperty(schema, "reason")) {
+      return def;
+    }
+
+    // Deep clone to avoid mutating shared refs
+    const newProperties = { ...properties, reason: { type: "string" } };
+    const existingRequired = Array.isArray(schema.required)
+      ? [...schema.required, "reason"]
+      : ["reason"];
+
+    return {
+      ...def,
+      input_schema: {
+        ...schema,
+        properties: newProperties,
+        required: existingRequired,
+      },
+    };
+  });
+}
+
+/**
+ * Checks whether a JSON Schema defines a given property name.
+ * Walks `allOf`, `oneOf`, `anyOf` recursively.
+ * Fail-closed on `$ref`: returns false if a `$ref` is encountered.
+ */
+export function schemaDefinesProperty(
+  schema: unknown,
+  propertyName: string,
+): boolean {
+  if (schema == null || typeof schema !== "object") {
+    return false;
+  }
+
+  const s = schema as Record<string, unknown>;
+
+  // Fail-closed on $ref — we can't resolve it, so treat as "doesn't define it"
+  if ("$ref" in s) {
+    return false;
+  }
+
+  // Check direct properties
+  if (
+    s.properties &&
+    typeof s.properties === "object" &&
+    propertyName in (s.properties as Record<string, unknown>)
+  ) {
+    return true;
+  }
+
+  // Walk composite keywords
+  for (const keyword of ["allOf", "oneOf", "anyOf"] as const) {
+    const arr = s[keyword];
+    if (Array.isArray(arr)) {
+      for (const member of arr) {
+        if (schemaDefinesProperty(member, propertyName)) {
+          return true;
+        }
+      }
+    }
+  }
+
+  return false;
+}

package/src/tools/skills/load.ts

@@ -119,11 +119,6 @@ export class SkillLoadTool implements Tool {
             type: "string",
             description: "The skill id or skill name to load.",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are loading and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
         required: ["skill"],
       },

package/src/tools/swarm/delegate.ts

@@ -44,11 +44,6 @@ export const swarmDelegateTool: Tool = {
             description:
               "Maximum concurrent workers (1-6, default from config)",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are doing and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
         required: ["objective"],
       },

package/src/tools/system/avatar-generator.ts

@@ -2,8 +2,7 @@ import { randomUUID } from "node:crypto";
 import { mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
-import { routedGenerateAvatar } from "../../media/avatar-router.js";
-import { ManagedAvatarError } from "../../media/avatar-types.js";
+import { generateAvatar } from "../../media/avatar-router.js";
 import { mapGeminiError } from "../../media/gemini-image-service.js";
 import { RiskLevel } from "../../permissions/types.js";
 import type { ToolDefinition } from "../../providers/types.js";
@@ -41,11 +40,6 @@ export const setAvatarTool: Tool = {
               "A text description of the desired avatar appearance, " +
               'e.g. "a friendly purple cat with green eyes wearing a tiny hat".',
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are creating and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
         required: ["description"],
       },
@@ -75,7 +69,7 @@ export const setAvatarTool: Tool = {
         "Circular or rounded composition filling the canvas. " +
         "Subtle background color (not white or transparent).";
 
-      const result = await routedGenerateAvatar(prompt);
+      const result = await generateAvatar(prompt);
       if (!result.imageBase64) {
         return {
           content: "Error: No image data returned. Please try again.",
@@ -92,14 +86,7 @@ export const setAvatarTool: Tool = {
       writeFileSync(tmpPath, pngBuffer);
       renameSync(tmpPath, avatarPath);
 
-      log.info(
-        {
-          avatarPath,
-          pathUsed: result.pathUsed,
-          correlationId: result.correlationId,
-        },
-        "Avatar saved successfully",
-      );
+      log.info({ avatarPath }, "Avatar saved successfully");
 
       // Side-effect hook in tool-side-effects.ts broadcasts avatar_updated to all clients.
 
@@ -108,34 +95,6 @@ export const setAvatarTool: Tool = {
         isError: false,
       };
     } catch (error) {
-      if (error instanceof ManagedAvatarError) {
-        log.error(
-          {
-            error: error.message,
-            statusCode: error.statusCode,
-            code: error.code,
-          },
-          "Avatar generation failed (managed)",
-        );
-        if (error.statusCode === 429) {
-          return {
-            content:
-              "Avatar generation is currently rate limited. Please try again in a moment.",
-            isError: true,
-          };
-        }
-        if (error.statusCode >= 500) {
-          return {
-            content:
-              "Avatar generation is temporarily unavailable. Please try again later.",
-            isError: true,
-          };
-        }
-        return {
-          content: `Avatar generation failed: ${error.message}`,
-          isError: true,
-        };
-      }
       const message = mapGeminiError(error);
       log.error({ error: message }, "Avatar generation failed");
       return {

package/src/tools/ui-surface/definitions.ts

@@ -126,11 +126,6 @@ export const uiShowTool: Tool = {
             description:
               "Whether to block until the user interacts with an action. Defaults to true when actions are provided.",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are showing and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
         required: ["surface_type", "data"],
       },
@@ -168,11 +163,6 @@ export const uiUpdateTool: Tool = {
             type: "object",
             description: "Partial data to merge into the existing surface data",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are updating and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
         required: ["surface_id", "data"],
       },
@@ -204,11 +194,6 @@ export const uiDismissTool: Tool = {
             type: "string",
             description: "The ID of the surface to dismiss",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are dismissing and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
         required: ["surface_id"],
       },

package/src/tools/watch/screen-watch.ts

@@ -42,11 +42,6 @@ class ScreenWatchTool implements Tool {
             type: "string",
             description: "What to focus on observing",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are watching and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
         required: ["focus_area"],
       },

package/src/version.ts

@@ -32,3 +32,13 @@ function resolveVersion(): string {
 // Falls back to "0.0.0-dev" for local development, or resolves the dev
 // placeholder to package.json version when explicitly set in CI.
 export const APP_VERSION: string = resolveVersion();
+
+// Commit SHA is embedded at compile time via --define in CI.
+// Falls back to "unknown" for local development.
+function resolveCommitSha(): string {
+  const sha = process.env.COMMIT_SHA;
+  if (!sha || sha === "unknown") return "unknown";
+  return sha;
+}
+
+export const COMMIT_SHA: string = resolveCommitSha();

package/src/watcher/providers/github.ts

@@ -10,7 +10,8 @@
  * `notifications` scope (classic) or Notification read permission (fine-grained).
  */
 
-import { withValidToken } from "../../security/token-manager.js";
+import type { OAuthConnection } from "../../oauth/connection.js";
+import { resolveOAuthConnection } from "../../oauth/connection-resolver.js";
 import { getLogger } from "../../util/logger.js";
 import { truncate } from "../../util/truncate.js";
 import type {
@@ -21,8 +22,6 @@ import type {
 
 const log = getLogger("watcher:github");
 
-const GITHUB_API_BASE = "https://api.github.com";
-
 // ── API types ──────────────────────────────────────────────────────────────────
 
 interface GitHubNotification {
@@ -82,31 +81,32 @@ function notificationToItem(n: GitHubNotification): WatcherItem {
 
 /** Fetch a single page of notifications since a timestamp. */
 async function fetchNotificationsPage(
-  token: string,
+  connection: OAuthConnection,
   since: string,
   page: number,
 ): Promise<{ items: GitHubNotification[]; hasMore: boolean }> {
-  const params = new URLSearchParams({
-    all: "false", // only unread
-    since,
-    per_page: "50",
-    page: String(page),
-  });
-
-  const resp = await fetch(`${GITHUB_API_BASE}/notifications?${params}`, {
+  const resp = await connection.request({
+    method: "GET",
+    path: "/notifications",
+    query: {
+      all: "false", // only unread
+      since,
+      per_page: "50",
+      page: String(page),
+    },
     headers: {
-      Authorization: `Bearer ${token}`,
       Accept: "application/vnd.github+json",
       "X-GitHub-Api-Version": "2022-11-28",
     },
   });
 
-  if (!resp.ok) {
-    const body = await resp.text().catch(() => "");
+  if (resp.status >= 400) {
+    const body =
+      typeof resp.body === "string" ? resp.body : JSON.stringify(resp.body);
     throw new Error(`GitHub Notifications API ${resp.status}: ${body}`);
   }
 
-  const items = (await resp.json()) as GitHubNotification[];
+  const items = resp.body as GitHubNotification[];
   // GitHub returns 50 per page; if we got a full page there may be more
   const hasMore = items.length === 50;
   return { items, hasMore };
@@ -130,44 +130,43 @@ export const githubProvider: WatcherProvider = {
     _config: Record<string, unknown>,
     _watcherKey: string,
   ): Promise<FetchResult> {
-    return withValidToken(credentialService, async (token) => {
-      const since = watermark ?? new Date().toISOString();
-      const items: WatcherItem[] = [];
-      let page = 1;
-
-      while (true) {
-        const { items: pageItems, hasMore } = await fetchNotificationsPage(
-          token,
-          since,
-          page,
-        );
-
-        for (const n of pageItems) {
-          // Only surface notifications for reasons that warrant attention
-          const relevantReasons = new Set([
-            "assign",
-            "mention",
-            "review_requested",
-            "team_mention",
-          ]);
-          if (!relevantReasons.has(n.reason)) continue;
-
-          items.push(notificationToItem(n));
-        }
-
-        if (!hasMore) break;
-        page++;
+    const connection = resolveOAuthConnection(credentialService);
+    const since = watermark ?? new Date().toISOString();
+    const items: WatcherItem[] = [];
+    let page = 1;
+
+    while (true) {
+      const { items: pageItems, hasMore } = await fetchNotificationsPage(
+        connection,
+        since,
+        page,
+      );
+
+      for (const n of pageItems) {
+        // Only surface notifications for reasons that warrant attention
+        const relevantReasons = new Set([
+          "assign",
+          "mention",
+          "review_requested",
+          "team_mention",
+        ]);
+        if (!relevantReasons.has(n.reason)) continue;
+
+        items.push(notificationToItem(n));
       }
 
-      // New watermark: the time just before we fetched so we don't miss events
-      // that arrive between poll cycles.
-      const newWatermark = new Date().toISOString();
+      if (!hasMore) break;
+      page++;
+    }
 
-      log.info(
-        { count: items.length, watermark: newWatermark },
-        "GitHub: fetched new notifications",
-      );
-      return { items, watermark: newWatermark };
-    });
+    // New watermark: the time just before we fetched so we don't miss events
+    // that arrive between poll cycles.
+    const newWatermark = new Date().toISOString();
+
+    log.info(
+      { count: items.length, watermark: newWatermark },
+      "GitHub: fetched new notifications",
+    );
+    return { items, watermark: newWatermark };
   },
 };