@vellumai/assistant 0.4.3 → 0.4.4

package/src/runtime/tool-grant-request-helper.ts

@@ -128,6 +128,7 @@ export function createOrReuseToolGrantRequest(
     questionText,
     expiresAt: new Date(Date.now() + GUARDIAN_APPROVAL_TTL_MS).toISOString(),
   });
+  const requestCode = canonicalRequest.requestCode ?? canonicalRequest.id.slice(0, 6).toUpperCase();
 
   // Emit notification so guardian is alerted. Uses 'guardian.question' as
   // sourceEventName so that existing request-code guidance in the notification
@@ -145,7 +146,8 @@ export function createOrReuseToolGrantRequest(
     },
     contextPayload: {
       requestId: canonicalRequest.id,
-      requestCode: canonicalRequest.requestCode,
+      requestKind: 'tool_grant_request',
+      requestCode,
       sourceChannel,
       requesterExternalUserId,
       requesterChatId: requesterChatId ?? null,

package/src/security/oauth2.ts

@@ -179,12 +179,19 @@ async function runGatewayFlow(
   codeChallenge: string,
   state: string,
 ): Promise<OAuth2FlowResult> {
+  // Dynamic imports required here to avoid circular dependencies with
+  // config/loader → security → oauth2 module chains.
   const { loadConfig } = await import('../config/loader.js');
   const { getOAuthCallbackUrl } = await import('../inbound/public-ingress-urls.js');
+  const { resolveCallbackUrl } = await import('../inbound/platform-callback-registration.js');
   const { registerPendingCallback } = await import('./oauth-callback-registry.js');
 
   const appConfig = loadConfig();
-  const redirectUri = getOAuthCallbackUrl(appConfig);
+  const redirectUri = await resolveCallbackUrl(
+    () => getOAuthCallbackUrl(appConfig),
+    'webhooks/oauth/callback',
+    'oauth',
+  );
 
   const codePromise = new Promise<string>((resolve, reject) => {
     registerPendingCallback(state, resolve, reject);
@@ -385,12 +392,19 @@ export async function prepareOAuth2Flow(
     return prepareLoopbackFlow(config, options?.loopbackPort);
   }
 
+  // Dynamic imports required here to avoid circular dependencies with
+  // config/loader → security → oauth2 module chains.
   const { loadConfig } = await import('../config/loader.js');
   const { getOAuthCallbackUrl } = await import('../inbound/public-ingress-urls.js');
+  const { resolveCallbackUrl } = await import('../inbound/platform-callback-registration.js');
   const { registerPendingCallback } = await import('./oauth-callback-registry.js');
 
   const appConfig = loadConfig();
-  const redirectUri = getOAuthCallbackUrl(appConfig);
+  const redirectUri = await resolveCallbackUrl(
+    () => getOAuthCallbackUrl(appConfig),
+    'webhooks/oauth/callback',
+    'oauth',
+  );
 
   const codeVerifier = generateCodeVerifier();
   const codeChallenge = generateCodeChallenge(codeVerifier);
@@ -590,6 +604,8 @@ export async function startOAuth2Flow(
 
   let hasPublicUrl = false;
   try {
+    // Dynamic imports required here to avoid circular dependencies with
+    // config/loader → security → oauth2 module chains.
     const { loadConfig } = await import('../config/loader.js');
     const { getPublicBaseUrl } = await import('../inbound/public-ingress-urls.js');
     getPublicBaseUrl(loadConfig());
@@ -598,6 +614,15 @@ export async function startOAuth2Flow(
     // No public URL configured
   }
 
+  // When containerized with a platform, callback routes are registered
+  // through the platform gateway — treat as having a public URL.
+  if (!hasPublicUrl) {
+    const { shouldUsePlatformCallbacks } = await import('../inbound/platform-callback-registration.js');
+    if (shouldUsePlatformCallbacks()) {
+      hasPublicUrl = true;
+    }
+  }
+
   // Determine transport: explicit option > auto-detect from config
   const transport = options?.callbackTransport
     ?? (hasPublicUrl ? 'gateway' : 'loopback');

package/src/security/token-manager.ts

@@ -13,6 +13,16 @@ import { getSecureKey, setSecureKey } from './secure-keys.js';
 
 const log = getLogger('token-manager');
 
+const MESSAGING_SERVICES = new Set(['integration:gmail', 'integration:slack']);
+
+function recoveryHint(service: string): string {
+  const shortName = service.startsWith('integration:') ? service.slice('integration:'.length) : service;
+  if (MESSAGING_SERVICES.has(service)) {
+    return ` Reconnect ${shortName} — follow the Error Recovery steps in the messaging skill. Do not present options or explain the error to the user.`;
+  }
+  return ` Re-authorization required for ${shortName}. Do not present options or explain the error to the user.`;
+}
+
 /** Buffer before expiry to trigger proactive refresh (5 minutes). */
 const EXPIRY_BUFFER_MS = 5 * 60 * 1000;
 
@@ -113,7 +123,7 @@ function isTokenExpired(service: string): boolean {
 async function doRefresh(service: string): Promise<string> {
   const refreshToken = getSecureKey(`credential:${service}:refresh_token`);
   if (!refreshToken) {
-    throw new TokenExpiredError(service, `No refresh token available for "${service}". Re-authorization required.`);
+    throw new TokenExpiredError(service, `No refresh token available for "${service}". Re-authorization required.${recoveryHint(service)}`);
   }
 
   const meta = getCredentialMetadata(service, 'access_token');
@@ -131,7 +141,7 @@ async function doRefresh(service: string): Promise<string> {
       : '';
     throw new TokenExpiredError(
       service,
-      `Missing OAuth2 refresh config for "${service}".${hint} Please reconnect via chat to re-authorize.`,
+      `Missing OAuth2 refresh config for "${service}".${hint}${recoveryHint(service)}`,
     );
   }
 
@@ -145,7 +155,7 @@ async function doRefresh(service: string): Promise<string> {
     throw new TokenExpiredError(
       service,
       `Token refresh for "${service}" is temporarily suspended after ${state.consecutiveFailures} consecutive failures. ` +
-      `Retrying in ${Math.ceil(remainingMs / 1000)}s. Please try again later or re-authorize.`,
+      `Retrying in ${Math.ceil(remainingMs / 1000)}s.${recoveryHint(service)}`,
     );
   }
 
@@ -156,16 +166,23 @@ async function doRefresh(service: string): Promise<string> {
     result = await refreshOAuth2Token(resolvedTokenUrl, clientId, refreshToken, clientSecret, authMethod);
   } catch (err) {
     recordRefreshFailure(service);
+    if (isCredentialError(err)) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new TokenExpiredError(service, `Token refresh failed for "${service}": ${msg}.${recoveryHint(service)}`);
+    }
+    // Transient errors (network failures, 5xx) are re-thrown as-is so
+    // upstream retry/backoff logic can handle them without triggering
+    // unnecessary reauthorization flows.
     throw err;
   }
 
   if (!setSecureKey(`credential:${service}:access_token`, result.accessToken)) {
-    throw new Error(`Failed to store refreshed access token for "${service}"`);
+    throw new TokenExpiredError(service, `Failed to store refreshed access token for "${service}".`);
   }
 
   if (result.refreshToken) {
     if (!setSecureKey(`credential:${service}:refresh_token`, result.refreshToken)) {
-      throw new Error(`Failed to store refreshed refresh token for "${service}"`);
+      throw new TokenExpiredError(service, `Failed to store refreshed refresh token for "${service}".`);
     }
   }
 
@@ -197,11 +214,7 @@ export async function withValidToken<T>(
 ): Promise<T> {
   let token = getSecureKey(`credential:${service}:access_token`);
   if (!token) {
-    const isGoogle = service === 'integration:gmail';
-    const googleHint = isGoogle
-      ? ' Do NOT fabricate credentials. Install and load the "google-oauth-setup" skill to set up OAuth credentials properly.'
-      : '';
-    throw new TokenExpiredError(service, `No access token found for "${service}". Authorization required.${googleHint}`);
+    throw new TokenExpiredError(service, `No access token found for "${service}". Authorization required.${recoveryHint(service)}`);
   }
 
   // Proactively refresh if expired or about to expire.
@@ -227,3 +240,26 @@ function is401Error(err: unknown): boolean {
   }
   return false;
 }
+
+/**
+ * Distinguish credential-specific refresh failures (which need reauthorization)
+ * from transient errors (network timeouts, 5xx) that can be retried.
+ *
+ * refreshOAuth2Token() throws Error with messages like:
+ *   "OAuth2 token refresh failed (HTTP 401: invalid_client)"
+ *   "OAuth2 token refresh failed (HTTP 400: invalid_grant)"
+ *   "OAuth2 token refresh failed (HTTP 500)"
+ *
+ * Credential errors: 400 with invalid_grant or invalid_client, 401, 403.
+ * Everything else (5xx, network errors, non-credential 400s) is transient.
+ */
+function isCredentialError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const msg = err.message;
+  // 401/403 are always credential errors
+  if (/HTTP\s+40[13]\b/.test(msg)) return true;
+  // 400 with invalid_grant means the refresh token is revoked/expired;
+  // invalid_client means client credentials are bad/rotated
+  if (/HTTP\s+400\b/.test(msg) && /invalid_grant|invalid_client/.test(msg)) return true;
+  return false;
+}

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

@@ -248,9 +248,10 @@ export async function executeBrowserNavigate(
       routeHandler = null;
     }
 
-    // In CDP mode, keep the browser minimized unless a handoff is active.
-    if (browserManager.browserMode === 'cdp' && !browserManager.isInteractive(context.sessionId)) {
-      await browserManager.moveWindowOffscreen();
+    // Reposition the browser window after navigation so the user can watch.
+    // positionWindowSidebar() is a no-op when browserCdpSession is unavailable.
+    if (!browserManager.isInteractive(context.sessionId)) {
+      await browserManager.positionWindowSidebar();
     }
 
     if (blockedUrl) {

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

@@ -1,7 +1,7 @@
 import type { ServerMessage } from '../../daemon/ipc-contract.js';
 import { getLogger } from '../../util/logger.js';
 import { browserManager } from './browser-manager.js';
-import { getScreencastSurfaceId } from './browser-screencast.js';
+import { isScreencastActive } from './browser-screencast.js';
 
 const log = getLogger('browser-handoff');
 
@@ -28,6 +28,8 @@ export async function startHandoff(
   log.info({ sessionId, reason: options.reason }, 'Starting handoff to user');
 
   // Bring Chrome to the front so the user can interact directly.
+  // The window is already sized/positioned in top-right via positionWindowSidebar(),
+  // so no repositioning needed.
   if (options.bringToFront) {
     try {
       const page = await browserManager.getOrCreateSessionPage(sessionId);
@@ -35,24 +37,19 @@ export async function startHandoff(
     } catch (err) {
       log.warn({ err, sessionId }, 'Failed to bring browser to front');
     }
-    await browserManager.moveWindowOnscreen();
   }
 
-  const surfaceId = getScreencastSurfaceId(sessionId);
-  if (!surfaceId) {
-    log.warn({ sessionId }, 'No active screencast surface for handoff');
-    // Move window back offscreen if we brought it to front
-    if (options.bringToFront) {
-      await browserManager.moveWindowOffscreen();
-    }
+  if (!isScreencastActive(sessionId)) {
+    log.warn({ sessionId }, 'No active browser session for handoff');
     return;
   }
 
-  // Send interactive mode change with reason and message
+  // Send interactive mode change with reason and message.
+  // surfaceId uses sessionId as a stable identifier since PiP surfaces are removed.
   sendToClient({
     type: 'browser_interactive_mode_changed',
     sessionId,
-    surfaceId,
+    surfaceId: sessionId,
     enabled: true,
     reason: options.reason,
     message: options.message,
@@ -60,18 +57,13 @@ export async function startHandoff(
 
   browserManager.setInteractiveMode(sessionId, true);
 
-  // Wait for user to hand back control (5 min timeout)
+  // Wait for user to hand back control (5 min timeout, or auto-detect URL change)
   await browserManager.waitForHandoffComplete(sessionId);
 
-  // Move Chrome back offscreen after handoff.
-  if (options.bringToFront) {
-    await browserManager.moveWindowOffscreen();
-  }
-
   sendToClient({
     type: 'browser_interactive_mode_changed',
     sessionId,
-    surfaceId,
+    surfaceId: sessionId,
     enabled: false,
   } as ServerMessage);
 

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

@@ -10,10 +10,19 @@ import { checkBrowserRuntime } from './runtime-check.js';
 
 const log = getLogger('browser-manager');
 
+/**
+ * Returns true when the host has a GUI capable of displaying a browser window.
+ * macOS and Windows always have a display; Linux requires DISPLAY or WAYLAND_DISPLAY.
+ */
+function canDisplayGui(): boolean {
+  if (process.platform === 'darwin' || process.platform === 'win32') return true;
+  return !!(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
+}
+
 // Screencast capture dimensions — used by coordinate math across the browser module
 // to map between page coordinates and screencast-frame coordinates.
-export const SCREENCAST_WIDTH = 800;
-export const SCREENCAST_HEIGHT = 600;
+export const SCREENCAST_WIDTH = 1280;
+export const SCREENCAST_HEIGHT = 800;
 
 function getDownloadsDir(): string {
   const dir = join(getDataDir(), 'browser-downloads');
@@ -260,9 +269,12 @@ class BrowserManager {
         }
 
         if (invokingSessionId && this.sessionSenders.get(invokingSessionId) && this._browserMode === 'headless') {
+          const willBeHeaded = canDisplayGui();
           log.info(
-            { sessionId: invokingSessionId },
-            'CDP unavailable/declined; staying in headless mode (no visible browser window will be auto-launched)',
+            { sessionId: invokingSessionId, willBeHeaded },
+            willBeHeaded
+              ? 'CDP unavailable/declined; launching visible browser (display available)'
+              : 'CDP unavailable/declined; staying in headless mode (no display available)',
           );
         }
       }
@@ -304,8 +316,10 @@ class BrowserManager {
       }
 
       const launch = launchPersistentContext ?? await getDefaultLaunchFn();
-      const ctx = await launch(profileDir, { headless: true });
-      log.info({ profileDir }, 'Browser context created');
+      const headless = !canDisplayGui();
+      const ctx = await launch(profileDir, { headless });
+      this._browserLaunched = true;
+      log.info({ profileDir, headless }, headless ? 'Browser context created (headless)' : 'Browser context created (visible)');
       return ctx;
     })();
 
@@ -391,9 +405,22 @@ class BrowserManager {
     // Track downloads for this page
     this.setupDownloadTracking(sessionId, page);
 
-    // In CDP mode, keep the window minimized unless we're in an active handoff.
-    if (this._browserMode === 'cdp' && !this.interactiveModeSessions.has(sessionId)) {
-      await this.moveWindowOffscreen();
+    // For launched browsers (not CDP-connected), create a page-level CDP session
+    // so we can position the browser window. Browser domain commands (setWindowBounds,
+    // getWindowForTarget) are accessible from page-level CDP sessions.
+    if (!this.browserCdpSession && this._browserLaunched && this._browserMode !== 'cdp') {
+      try {
+        const rawPage = page as unknown as RawPlaywrightPage;
+        this.browserCdpSession = await rawPage.context().newCDPSession(rawPage);
+        await this.ensureBrowserWindowId();
+      } catch (err) {
+        log.warn({ err }, 'Failed to create CDP session for window positioning');
+      }
+    }
+
+    // Position the browser window so the user can watch.
+    if (this.browserCdpSession && !this.interactiveModeSessions.has(sessionId)) {
+      await this.positionWindowSidebar();
     }
 
     log.debug({ sessionId }, 'Session page created');
@@ -530,7 +557,7 @@ class BrowserManager {
 
     await cdp.send('Page.startScreencast', {
       format: 'jpeg',
-      quality: 30,
+      quality: 45,
       maxWidth: SCREENCAST_WIDTH,
       maxHeight: SCREENCAST_HEIGHT,
       everyNthFrame: 4,
@@ -569,7 +596,7 @@ class BrowserManager {
 
   /**
    * Create a browser-level CDP session and discover the window ID.
-   * Called once after browser launch/connect so moveWindowOffscreen/Onscreen can work.
+   * Called once after browser launch/connect so positionWindowSidebar/moveWindowOnscreen can work.
    */
   private async initBrowserCdpSession(): Promise<void> {
     if (!this.cdpBrowser) return;
@@ -607,28 +634,24 @@ class BrowserManager {
   }
 
   /**
-   * Hide the browser window during non-handoff automation to avoid focus theft.
+   * Position the browser window small on the right side of the screen so the
+   * user can watch automation while still seeing assistant messages on the left.
    */
-  async moveWindowOffscreen(): Promise<void> {
+  async positionWindowSidebar(): Promise<void> {
     if (!this.browserCdpSession) return;
     const windowId = await this.ensureBrowserWindowId();
     if (windowId == null) return;
     try {
       await this.browserCdpSession.send('Browser.setWindowBounds', {
         windowId,
-        bounds: { windowState: 'minimized' },
+        bounds: { left: 480, top: 40, width: 940, height: 700, windowState: 'normal' },
       });
-      log.debug('moveWindowOffscreen: minimized browser window via CDP');
+      log.debug('positionWindowSidebar: placed browser window in top-right');
     } catch (err) {
-      log.warn({ err }, 'moveWindowOffscreen: minimize failed, attempting offscreen bounds');
-      try {
-        await this.browserCdpSession.send('Browser.setWindowBounds', {
-          windowId,
-          bounds: { left: -32000, top: -32000, windowState: 'normal' },
-        });
-      } catch (boundsErr) {
-        log.warn({ err: boundsErr }, 'moveWindowOffscreen: offscreen bounds failed');
-      }
+      log.warn({ err }, 'positionWindowSidebar: failed to position window');
+      // CDP session may be stale (e.g. page closed) — clear it so it gets recreated
+      this.browserCdpSession = null;
+      this.browserWindowId = null;
     }
   }
 
@@ -642,7 +665,7 @@ class BrowserManager {
     try {
       await this.browserCdpSession.send('Browser.setWindowBounds', {
         windowId,
-        bounds: { left: 100, top: 100, width: 1280, height: 960, windowState: 'normal' },
+        bounds: { left: 200, top: 40, width: 1100, height: 820, windowState: 'normal' },
       });
       log.debug('moveWindowOnscreen: moved window onscreen via CDP');
     } catch (err) {
@@ -676,9 +699,16 @@ class BrowserManager {
       existing();
     }
 
+    // Capture the initial URL so we can auto-detect page changes
+    const page = this.pages.get(sessionId);
+    const initialUrl = page && !page.isClosed() ? page.url() : null;
+
     return new Promise<void>((resolve) => {
+      let pollTimer: ReturnType<typeof setInterval> | null = null;
+
       const resolver = () => {
         clearTimeout(timer);
+        if (pollTimer) clearInterval(pollTimer);
         if (this.handoffResolvers.get(sessionId) === resolver) {
           this.handoffResolvers.delete(sessionId);
         }
@@ -686,6 +716,7 @@ class BrowserManager {
       };
 
       const timer = setTimeout(() => {
+        if (pollTimer) clearInterval(pollTimer);
         if (this.handoffResolvers.get(sessionId) === resolver) {
           this.handoffResolvers.delete(sessionId);
         }
@@ -694,6 +725,30 @@ class BrowserManager {
       }, timeoutMs);
 
       this.handoffResolvers.set(sessionId, resolver);
+
+      // Poll for URL changes — auto-resolve when the page navigates
+      // (e.g., CAPTCHA solved, login redirect)
+      if (initialUrl && page) {
+        pollTimer = setInterval(() => {
+          try {
+            if (page.isClosed()) {
+              this.interactiveModeSessions.delete(sessionId);
+              resolver();
+              return;
+            }
+            const currentUrl = page.url();
+            if (currentUrl !== initialUrl) {
+              log.info({ sessionId, from: initialUrl, to: currentUrl }, 'Handoff auto-resolved: URL changed');
+              this.interactiveModeSessions.delete(sessionId);
+              resolver();
+            }
+          } catch {
+            // Page may have been closed — resolve gracefully
+            this.interactiveModeSessions.delete(sessionId);
+            resolver();
+          }
+        }, 2000);
+      }
     });
   }