@vellumai/assistant 0.4.46 → 0.4.49

package/src/telegram/bot-username.ts

@@ -1,13 +1,12 @@
 import { getConfig } from "../config/loader.js";
 
 /**
- * Read the Telegram bot username from config, falling back to the
- * TELEGRAM_BOT_USERNAME env var.
+ * Read the Telegram bot username from config.
  */
 export function getTelegramBotUsername(): string | undefined {
   const value = getConfig().telegram.botUsername;
   if (value.trim().length > 0) {
     return value.trim();
   }
-  return process.env.TELEGRAM_BOT_USERNAME || undefined;
+  return undefined;
 }

package/src/tools/apps/definitions.ts

@@ -51,11 +51,6 @@ const appOpenTool: Tool = {
             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"],
       },

package/src/tools/assets/materialize.ts

@@ -95,11 +95,6 @@ const definition: ToolDefinition = {
         description:
           "Path where the file should be written, relative to (or inside) the sandbox working directory.",
       },
-      reason: {
-        type: "string",
-        description:
-          "Brief non-technical explanation of what you are saving and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-      },
     },
     required: ["attachment_id", "destination_path"],
   },

package/src/tools/assets/search.ts

@@ -298,11 +298,6 @@ const definition: ToolDefinition = {
         type: "number",
         description: `Maximum results to return (default ${DEFAULT_LIMIT}, max ${MAX_RESULTS}).`,
       },
-      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: [],
   },

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

@@ -44,11 +44,6 @@ class BrowserNavigateTool implements Tool {
             description:
               "If true, allows navigation to localhost/private-network hosts. Disabled by default for SSRF safety.",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are navigating to and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
         required: ["url"],
       },
@@ -80,13 +75,7 @@ class BrowserSnapshotTool implements Tool {
       description: this.description,
       input_schema: {
         type: "object",
-        properties: {
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are inspecting and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
-        },
+        properties: {},
       },
     };
   }
@@ -122,11 +111,6 @@ class BrowserScreenshotTool implements Tool {
             description:
               "Capture the full scrollable page instead of just the viewport.",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are capturing and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
       },
     };
@@ -163,11 +147,6 @@ class BrowserCloseTool implements Tool {
             description:
               "If true, close all browser pages and the browser context. Default: false (close only the current session page).",
           },
-          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.",
-          },
         },
       },
     };
@@ -214,11 +193,6 @@ class BrowserClickTool implements Tool {
             description:
               "Max time in ms to wait for the element to be clickable (default: 10000).",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are clicking and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
       },
     };
@@ -273,11 +247,6 @@ class BrowserTypeTool implements Tool {
             type: "boolean",
             description: "If true, press Enter after typing the text.",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are typing and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
         required: ["text"],
       },
@@ -323,11 +292,6 @@ class BrowserPressKeyTool implements Tool {
             type: "string",
             description: "Optional CSS selector to target.",
           },
-          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: ["key"],
       },
@@ -378,11 +342,6 @@ class BrowserScrollTool implements Tool {
             type: "string",
             description: "Optional CSS selector of element to scroll within.",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are scrolling to see and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
         required: ["direction"],
       },
@@ -437,11 +396,6 @@ class BrowserSelectOptionTool implements Tool {
             type: "number",
             description: "The zero-based index of the <option> to select.",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are selecting and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
       },
     };
@@ -483,11 +437,6 @@ class BrowserHoverTool implements Tool {
             description:
               "A CSS selector to target. Used as fallback when element_id is not available.",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are hovering over and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
       },
     };
@@ -537,11 +486,6 @@ class BrowserWaitForTool implements Tool {
             description:
               "Maximum wait time in milliseconds (default and max: 30000).",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are waiting for and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
       },
     };
@@ -578,11 +522,6 @@ class BrowserExtractTool implements Tool {
             description:
               "If true, include a list of links found on the page (up to 200).",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are extracting and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
       },
     };
@@ -634,11 +573,6 @@ class BrowserFillCredentialTool implements Tool {
             type: "boolean",
             description: "Press Enter after filling",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are filling in and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
         required: ["service", "field"],
       },

package/src/tools/browser/network-recorder.ts

@@ -1,5 +1,5 @@
 /**
- * CDP Network recorder for Ride Shotgun "learn" mode.
+ * CDP Network recorder.
  *
  * Connects directly to Chrome's CDP WebSocket endpoint to record
  * Network.* events across all tabs the user browses.

package/src/tools/browser/network-recording-types.ts

@@ -1,4 +1,4 @@
-/** Types for CDP network recording used by Ride Shotgun "learn" mode. */
+/** Types for CDP network recording. */
 
 export interface NetworkRecordedRequest {
   method: string;

package/src/tools/claude-code/claude-code.ts

@@ -123,11 +123,6 @@ export const claudeCodeTool: Tool = {
             description:
               "Worker profile that scopes tool access. Defaults to general (backward compatible).",
           },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are delegating and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
         },
       },
     };

package/src/tools/computer-use/definitions.ts

@@ -34,7 +34,7 @@ const reasonProperty = {
 export const computerUseClickTool: Tool = {
   name: "computer_use_click",
   description:
-    "Click on a UI element by its [ID] from the accessibility tree, or at raw screen coordinates as fallback. Supports single click, double-click, and right-click via the click_type parameter.",
+    "Click an element on screen. Prefer element_id (from the accessibility tree) over x/y coordinates.",
   category: "computer-use",
   defaultRiskLevel: RiskLevel.Low,
   executionMode: "proxy",
@@ -86,7 +86,7 @@ export const computerUseClickTool: Tool = {
 export const computerUseTypeTextTool: Tool = {
   name: "computer_use_type_text",
   description:
-    "Type text at the current cursor position. The target field must already be focused (click it first).",
+    "Type text at the current cursor position. First click a text field (by element_id) to focus it, then call this tool. If a field shows 'FOCUSED', skip the click.",
   category: "computer-use",
   defaultRiskLevel: RiskLevel.Low,
   executionMode: "proxy",
@@ -352,13 +352,7 @@ export const computerUseOpenAppTool: Tool = {
 export const computerUseRunAppleScriptTool: Tool = {
   name: "computer_use_run_applescript",
   description:
-    "Execute an AppleScript to control applications via Apple's scripting bridge. " +
-    "Use this for operations that are more reliable through scripting than UI interaction: " +
-    "setting a browser URL directly, navigating Finder to a path, querying app state " +
-    "(tab count, window titles, document status), or clicking deeply nested menu items. " +
-    "The script's return value (if any) will be reported back. " +
-    'NEVER use "do shell script" — it is blocked for security. ' +
-    "Keep scripts short and targeted to a single operation.",
+    "Run an AppleScript command. Prefer this over click/type when possible — it doesn't move the cursor or interrupt the user. Never use 'do shell script' inside AppleScript (blocked for security).",
   category: "computer-use",
   defaultRiskLevel: RiskLevel.Low,
   executionMode: "proxy",
@@ -395,7 +389,8 @@ export const computerUseRunAppleScriptTool: Tool = {
 
 export const computerUseDoneTool: Tool = {
   name: "computer_use_done",
-  description: "Task is complete",
+  description:
+    "Signal that the computer use task is complete. Provide a summary of what was accomplished. This ends the computer use session.",
   category: "computer-use",
   defaultRiskLevel: RiskLevel.Low,
   executionMode: "proxy",
@@ -428,7 +423,7 @@ export const computerUseDoneTool: Tool = {
 export const computerUseRespondTool: Tool = {
   name: "computer_use_respond",
   description:
-    "Respond directly to the user with a text answer. Use this when the user is asking a question (about their schedule, meetings, calendar, etc.) rather than asking you to control the computer.",
+    "Respond to the user with a text answer instead of performing computer actions. Use this when you can answer directly without interacting with the screen.",
   category: "computer-use",
   defaultRiskLevel: RiskLevel.Low,
   executionMode: "proxy",
@@ -458,11 +453,41 @@ export const computerUseRespondTool: Tool = {
   execute: proxyExecute,
 };
 
+// ---------------------------------------------------------------------------
+// observe
+// ---------------------------------------------------------------------------
+
+export const computerUseObserveTool: Tool = {
+  name: "computer_use_observe",
+  description:
+    "Capture the current screen state. Returns the accessibility tree with [ID] element references and optionally a screenshot.\n\nThe accessibility tree shows interactive elements like [3] AXButton 'Save' or [17] AXTextField 'Search'. Use element_id to target these elements in subsequent actions — this is much more reliable than pixel coordinates.\n\nCall this before your first computer use action, or to check screen state without acting.",
+  category: "computer-use",
+  defaultRiskLevel: RiskLevel.Low,
+  executionMode: "proxy",
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: "object",
+        properties: {
+          reason: reasonProperty,
+        },
+        required: ["reason"],
+      },
+    };
+  },
+
+  execute: proxyExecute,
+};
+
 // ---------------------------------------------------------------------------
 // All tools exported as array for convenience
 // ---------------------------------------------------------------------------
 
 export const allComputerUseTools: Tool[] = [
+  computerUseObserveTool,
   computerUseClickTool,
   computerUseTypeTextTool,
   computerUseKeyTool,
@@ -474,3 +499,13 @@ export const allComputerUseTools: Tool[] = [
   computerUseDoneTool,
   computerUseRespondTool,
 ];
+
+/**
+ * Tools safe for the legacy fallback path (no skill projection).
+ *
+ * Excludes `computer_use_observe` because the macOS client doesn't handle it
+ * in the legacy code path — it falls back to `.done` which skips sending an
+ * observation, causing the daemon to block on `pendingObservation` until timeout.
+ */
+export const legacyFallbackComputerUseTools: Tool[] =
+  allComputerUseTools.filter((t) => t.name !== "computer_use_observe");

package/src/tools/computer-use/registry.ts

@@ -1,11 +1,10 @@
 /**
  * Registers computer-use tools with the daemon's tool registry.
  *
- * The 12 computer_use_* action tools and the computer_use_request_control
- * escalation tool are now provided by the bundled computer-use skill.
- * This module retains registerComputerUseActionTools() for backward
- * compatibility (used by tests), but it is no longer called during
- * normal startup.
+ * The computer_use_* action tools are now provided by the bundled
+ * computer-use skill. This module retains registerComputerUseActionTools()
+ * for backward compatibility (used by tests), but it is no longer called
+ * during normal startup.
  */
 
 import { registerTool } from "../registry.js";

package/src/tools/credentials/broker.ts

@@ -1,5 +1,6 @@
 import { v4 as uuid } from "uuid";
 
+import { credentialKey } from "../../security/credential-key.js";
 import { getSecureKey } from "../../security/secure-keys.js";
 import { getLogger } from "../../util/logger.js";
 import type {
@@ -46,7 +47,7 @@ export class CredentialBroker {
    * browserFill or consume call for this service/field pair, then discarded.
    */
   injectTransient(service: string, field: string, value: string): void {
-    const key = `credential:${service}:${field}`;
+    const key = credentialKey(service, field);
     this.transientValues.set(key, { value });
     log.info(
       { service, field },
@@ -123,7 +124,7 @@ export class CredentialBroker {
     }
 
     token.consumed = true;
-    const storageKey = `credential:${token.service}:${token.field}`;
+    const storageKey = credentialKey(token.service, token.field);
     // Check for transient value first (one-time send) — consume and return the value
     // directly since transient values are never persisted to secure storage.
     const transient = this.transientValues.get(storageKey);
@@ -211,7 +212,7 @@ export class CredentialBroker {
       }
     }
 
-    const storageKey = `credential:${request.service}:${request.field}`;
+    const storageKey = credentialKey(request.service, request.field);
     // Check transient values first (one-time send), then fall back to keychain.
     // Deletion is deferred until after a successful fill so the value survives
     // transient failures (e.g. stale element, page navigation, Playwright timeout).
@@ -299,7 +300,7 @@ export class CredentialBroker {
       };
     }
 
-    const storageKey = `credential:${request.service}:${request.field}`;
+    const storageKey = credentialKey(request.service, request.field);
     const transient = this.transientValues.get(storageKey);
     const value = transient?.value ?? getSecureKey(storageKey);
     if (!value) {

package/src/tools/credentials/metadata-store.ts

@@ -4,6 +4,11 @@
  * Persists non-secret metadata about credentials (policy, timestamps, IDs)
  * in a versioned JSON file under protected storage. Secret values remain
  * in the secure key backend only.
+ *
+ * OAuth-specific fields (expiresAt, grantedScopes, oauth2TokenUrl,
+ * oauth2ClientId, oauth2TokenEndpointAuthMethod, hasRefreshToken) are now
+ * exclusively managed by the SQLite oauth-store and have been removed
+ * from this interface as of v5.
  */
 
 import { randomUUID } from "node:crypto";
@@ -21,16 +26,6 @@ export interface CredentialMetadata {
   allowedTools: string[];
   allowedDomains: string[];
   usageDescription?: string;
-  expiresAt?: number;
-  grantedScopes?: string[];
-  /** OAuth2 token endpoint — enables autonomous token refresh without an IntegrationDefinition. */
-  oauth2TokenUrl?: string;
-  /** OAuth2 client ID — paired with oauth2TokenUrl for refresh. */
-  oauth2ClientId?: string;
-  /** OAuth2 client secret — for providers that require it (e.g. Slack). Stored in metadata for autonomous refresh. */
-  oauth2ClientSecret?: string;
-  /** How the client authenticates at the token endpoint (client_secret_basic or client_secret_post). */
-  oauth2TokenEndpointAuthMethod?: string;
   /** Human-friendly name for this credential (e.g. "fal-primary"). */
   alias?: string;
   /** Templates describing how to inject this credential into proxied requests. */
@@ -40,7 +35,7 @@ export interface CredentialMetadata {
 }
 
 /** Current on-disk schema version. */
-const CURRENT_VERSION = 2;
+const CURRENT_VERSION = 5;
 
 interface MetadataFile {
   version: typeof CURRENT_VERSION;
@@ -88,9 +83,10 @@ function isValidCredentialRecord(
 }
 
 /**
- * Migrate a v1 record to v2 by backfilling new optional fields with defaults.
+ * Migrate any record to v5 by stripping OAuth-specific fields that are
+ * now exclusively managed by the SQLite oauth-store.
  */
-function migrateRecordV1toV2(
+function migrateRecordToV5(
   record: Record<string, unknown>,
 ): CredentialMetadata {
   return {
@@ -107,27 +103,6 @@ function migrateRecordV1toV2(
       typeof record.usageDescription === "string"
         ? record.usageDescription
         : undefined,
-    expiresAt:
-      typeof record.expiresAt === "number" ? record.expiresAt : undefined,
-    grantedScopes: Array.isArray(record.grantedScopes)
-      ? (record.grantedScopes as string[])
-      : undefined,
-    oauth2TokenUrl:
-      typeof record.oauth2TokenUrl === "string"
-        ? record.oauth2TokenUrl
-        : undefined,
-    oauth2ClientId:
-      typeof record.oauth2ClientId === "string"
-        ? record.oauth2ClientId
-        : undefined,
-    oauth2ClientSecret:
-      typeof record.oauth2ClientSecret === "string"
-        ? record.oauth2ClientSecret
-        : undefined,
-    oauth2TokenEndpointAuthMethod:
-      typeof record.oauth2TokenEndpointAuthMethod === "string"
-        ? record.oauth2TokenEndpointAuthMethod
-        : undefined,
     alias: typeof record.alias === "string" ? record.alias : undefined,
     injectionTemplates: Array.isArray(record.injectionTemplates)
       ? (record.injectionTemplates as CredentialInjectionTemplate[])
@@ -148,7 +123,13 @@ function loadFile(): LoadResult {
       return { version: CURRENT_VERSION, credentials: [] };
     }
     const fileVersion = typeof data.version === "number" ? data.version : 1;
-    if (fileVersion !== 1 && fileVersion !== 2) {
+    if (
+      fileVersion !== 1 &&
+      fileVersion !== 2 &&
+      fileVersion !== 3 &&
+      fileVersion !== 4 &&
+      fileVersion !== 5
+    ) {
       // Unrecognized version (future, fractional, negative, zero) — refuse to touch it
       return { unknownVersion: true };
     }
@@ -159,8 +140,12 @@ function loadFile(): LoadResult {
     const validRecords = rawCredentials.filter(isValidCredentialRecord);
 
     if (fileVersion < CURRENT_VERSION) {
-      // Migrate from v1 to v2 and persist the upgrade so we don't re-migrate on every read
-      const credentials = validRecords.map(migrateRecordV1toV2);
+      // Migrate all older versions to v5 by stripping OAuth-specific fields
+      // and removing ghost refresh_token records
+      const filtered = validRecords.filter(
+        (r) => (r as Record<string, unknown>).field !== "refresh_token",
+      );
+      const credentials = filtered.map(migrateRecordToV5);
       const migrated: MetadataFile = { version: CURRENT_VERSION, credentials };
       try {
         saveFile(migrated);
@@ -214,14 +199,6 @@ export function upsertCredentialMetadata(
     allowedTools?: string[];
     allowedDomains?: string[];
     usageDescription?: string;
-    /** Pass `null` to explicitly clear a previously-set expiry. */
-    expiresAt?: number | null;
-    grantedScopes?: string[];
-    oauth2TokenUrl?: string;
-    oauth2ClientId?: string;
-    /** Pass `null` to explicitly clear a previously-set client secret. */
-    oauth2ClientSecret?: string | null;
-    oauth2TokenEndpointAuthMethod?: string;
     /** Pass `null` to explicitly clear a previously-set alias. */
     alias?: string | null;
     /** Pass `null` to explicitly clear injection templates. */
@@ -248,29 +225,6 @@ export function upsertCredentialMetadata(
       existing.allowedDomains = policy.allowedDomains;
     if (policy?.usageDescription !== undefined)
       existing.usageDescription = policy.usageDescription;
-    if (policy?.expiresAt !== undefined) {
-      if (policy.expiresAt == null) {
-        delete existing.expiresAt;
-      } else {
-        existing.expiresAt = policy.expiresAt;
-      }
-    }
-    if (policy?.grantedScopes !== undefined)
-      existing.grantedScopes = policy.grantedScopes;
-    if (policy?.oauth2TokenUrl !== undefined)
-      existing.oauth2TokenUrl = policy.oauth2TokenUrl;
-    if (policy?.oauth2ClientId !== undefined)
-      existing.oauth2ClientId = policy.oauth2ClientId;
-    if (policy?.oauth2ClientSecret !== undefined) {
-      if (policy.oauth2ClientSecret == null) {
-        delete existing.oauth2ClientSecret;
-      } else {
-        existing.oauth2ClientSecret = policy.oauth2ClientSecret;
-      }
-    }
-    if (policy?.oauth2TokenEndpointAuthMethod !== undefined)
-      existing.oauth2TokenEndpointAuthMethod =
-        policy.oauth2TokenEndpointAuthMethod;
     if (policy?.alias !== undefined) {
       if (policy.alias == null) {
         delete existing.alias;
@@ -297,12 +251,6 @@ export function upsertCredentialMetadata(
     allowedTools: policy?.allowedTools ?? [],
     allowedDomains: policy?.allowedDomains ?? [],
     usageDescription: policy?.usageDescription,
-    expiresAt: policy?.expiresAt ?? undefined,
-    grantedScopes: policy?.grantedScopes,
-    oauth2TokenUrl: policy?.oauth2TokenUrl,
-    oauth2ClientId: policy?.oauth2ClientId,
-    oauth2ClientSecret: policy?.oauth2ClientSecret ?? undefined,
-    oauth2TokenEndpointAuthMethod: policy?.oauth2TokenEndpointAuthMethod,
     alias: policy?.alias ?? undefined,
     injectionTemplates: policy?.injectionTemplates ?? undefined,
     createdAt: now,

package/src/tools/credentials/resolve.ts

@@ -6,6 +6,7 @@
  * secure key naming convention.
  */
 
+import { credentialKey } from "../../security/credential-key.js";
 import { matchHostPattern } from "./host-pattern-match.js";
 import {
   type CredentialMetadata,
@@ -33,7 +34,7 @@ function toResolved(metadata: CredentialMetadata): ResolvedCredential {
     credentialId: metadata.credentialId,
     service: metadata.service,
     field: metadata.field,
-    storageKey: `credential:${metadata.service}:${metadata.field}`,
+    storageKey: credentialKey(metadata.service, metadata.field),
     alias: metadata.alias,
     injectionTemplates: metadata.injectionTemplates ?? [],
     metadata,