@vellumai/assistant 0.6.2 → 0.6.4

package/src/tools/browser/cdp-client/index.ts

@@ -0,0 +1,28 @@
+export {
+  CdpInspectClient,
+  type CdpInspectClientOptions,
+  type CdpInspectHelpers,
+  createCdpInspectClient,
+} from "./cdp-inspect-client.js";
+export { CdpError, type CdpErrorCode } from "./errors.js";
+export {
+  createExtensionCdpClient,
+  ExtensionCdpClient,
+} from "./extension-cdp-client.js";
+export {
+  buildCandidateList,
+  buildChainedClient,
+  buildPinnedCandidateList,
+  getCdpClient,
+  type GetCdpClientOptions,
+} from "./factory.js";
+export { createLocalCdpClient, LocalCdpClient } from "./local-cdp-client.js";
+export type {
+  AttemptDiagnostic,
+  AttemptStage,
+  BackendCandidate,
+  BrowserMode,
+  CdpClient,
+  CdpClientKind,
+  ScopedCdpClient,
+} from "./types.js";

package/src/tools/browser/cdp-client/local-cdp-client.ts

@@ -0,0 +1,187 @@
+import { getLogger } from "../../../util/logger.js";
+import { browserManager } from "../browser-manager.js";
+import { CdpError } from "./errors.js";
+import type { CdpClientKind, ScopedCdpClient } from "./types.js";
+
+const log = getLogger("local-cdp-client");
+
+/**
+ * Minimal shape of the Playwright CDPSession we depend on. Avoids a
+ * direct Playwright type import so the CDP client stays buildable
+ * even when Playwright types are not present (dev builds, CI jobs
+ * that skip the playwright install).
+ */
+interface PlaywrightCdpSession {
+  send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+  detach(): Promise<void>;
+}
+
+/**
+ * Minimal shape of the Playwright Page we use for CDP session
+ * creation. Intentionally narrow so we never have to import the
+ * Playwright types directly from this module.
+ */
+interface RawPlaywrightPage {
+  context(): {
+    newCDPSession(page: unknown): Promise<PlaywrightCdpSession>;
+  };
+}
+
+/**
+ * Playwright-backed implementation of {@link ScopedCdpClient}. Used
+ * for CLI conversations, headless cloud conversations, unit tests,
+ * and any desktop conversation that does not have a `hostBrowserProxy`
+ * configured.
+ *
+ * LocalCdpClient owns only the per-conversation CDP session; the
+ * underlying Chromium is still launched and torn down by
+ * `browserManager.ensureContext()` / `browserManager.shutdown()`.
+ */
+export class LocalCdpClient implements ScopedCdpClient {
+  readonly kind: CdpClientKind = "local";
+
+  private sessionPromise: Promise<PlaywrightCdpSession> | null = null;
+  private disposed = false;
+
+  constructor(public readonly conversationId: string) {}
+
+  /**
+   * Lazily create (and cache) a Playwright CDP session for this
+   * conversation. Concurrent callers share the same in-flight promise
+   * so `newCDPSession` is only called once per LocalCdpClient
+   * instance.
+   *
+   * If the underlying browser launch / `newCDPSession` rejects (e.g.
+   * a transient Chromium spawn failure), the cached promise is
+   * cleared so the next `ensureSession()` call retries from scratch
+   * instead of replaying the same rejection forever.
+   */
+  private async ensureSession(): Promise<PlaywrightCdpSession> {
+    if (this.disposed) {
+      throw new CdpError("disposed", "LocalCdpClient already disposed");
+    }
+    if (this.sessionPromise) return this.sessionPromise;
+    const created = this.createSession();
+    this.sessionPromise = created;
+    // Clear the cached promise on rejection so the next call retries
+    // from scratch instead of replaying the same failure forever.
+    // Only clear if `created` is still the cached promise — a
+    // concurrent dispose may have already nulled it.
+    created.catch(() => {
+      if (this.sessionPromise === created) {
+        this.sessionPromise = null;
+      }
+    });
+    return created;
+  }
+
+  private async createSession(): Promise<PlaywrightCdpSession> {
+    const page = await browserManager.getOrCreateSessionPage(
+      this.conversationId,
+    );
+    const rawPage = page as unknown as RawPlaywrightPage;
+    const session = await rawPage.context().newCDPSession(rawPage);
+    log.debug(
+      { conversationId: this.conversationId },
+      "Created Playwright CDP session for LocalCdpClient",
+    );
+    return session;
+  }
+
+  async send<T = unknown>(
+    method: string,
+    params?: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): Promise<T> {
+    if (this.disposed) {
+      throw new CdpError("disposed", "LocalCdpClient already disposed", {
+        cdpMethod: method,
+        cdpParams: params,
+      });
+    }
+    if (signal?.aborted) {
+      throw new CdpError("aborted", "Aborted before send", {
+        cdpMethod: method,
+        cdpParams: params,
+      });
+    }
+    let session: PlaywrightCdpSession;
+    try {
+      session = await this.ensureSession();
+    } catch (err) {
+      if (signal?.aborted) {
+        throw new CdpError("aborted", "Aborted during send", {
+          cdpMethod: method,
+          cdpParams: params,
+          underlying: err,
+        });
+      }
+      // Re-throw existing CdpError instances unchanged so we don't
+      // double-wrap (e.g. a "disposed" error raised by a concurrent
+      // dispose landing during ensureSession()).
+      if (err instanceof CdpError) {
+        throw err;
+      }
+      // ensureSession failures (browser launch errors, Chromium
+      // spawn failures, etc) are surfaced as transport_error so
+      // callers can distinguish them from CDP protocol errors raised
+      // by session.send below.
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new CdpError("transport_error", msg, {
+        cdpMethod: method,
+        cdpParams: params,
+        underlying: err,
+      });
+    }
+    try {
+      const result = (await session.send(method, params)) as T;
+      return result;
+    } catch (err) {
+      if (signal?.aborted) {
+        throw new CdpError("aborted", "Aborted during send", {
+          cdpMethod: method,
+          cdpParams: params,
+          underlying: err,
+        });
+      }
+      if (err instanceof CdpError) {
+        throw err;
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new CdpError("cdp_error", msg, {
+        cdpMethod: method,
+        cdpParams: params,
+        underlying: err,
+      });
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    const pending = this.sessionPromise;
+    this.sessionPromise = null;
+    if (!pending) return;
+    pending
+      .then(async (session) => {
+        try {
+          await session.detach();
+        } catch (err) {
+          log.debug({ err }, "LocalCdpClient: session.detach threw (ignored)");
+        }
+      })
+      .catch(() => {
+        // Session never resolved — nothing to detach.
+      });
+  }
+}
+
+/**
+ * Factory for a fresh {@link LocalCdpClient} bound to a conversation.
+ * Keeping the constructor + factory split lets the cdp-client factory
+ * branch between local and extension transports without
+ * exposing the class directly to callers.
+ */
+export function createLocalCdpClient(conversationId: string): LocalCdpClient {
+  return new LocalCdpClient(conversationId);
+}

package/src/tools/browser/cdp-client/types.ts

@@ -0,0 +1,120 @@
+/**
+ * Minimal typed surface over Chrome DevTools Protocol. Implemented by
+ * LocalCdpClient (Playwright-backed, same-process Chromium),
+ * ExtensionCdpClient (routes through HostBrowserProxy to the user's
+ * Chrome via chrome.debugger), and CdpInspectClient (connects to a
+ * remote browser over a raw CDP WebSocket URL). Tools call
+ * `send(method, params)` with a CDP method name and return the raw
+ * CDP result object; errors are thrown as {@link CdpError}.
+ */
+export interface CdpClient {
+  /**
+   * Send a CDP command and await the result. `method` must be a
+   * well-known CDP method name (e.g. "Page.navigate",
+   * "Runtime.evaluate", "Accessibility.getFullAXTree"). `params` is
+   * forwarded verbatim.
+   *
+   * On success, returns the raw `result` object from the CDP response
+   * as `T`. On JSON-RPC error or transport failure, throws a
+   * {@link CdpError}. Abort propagates via `signal`; aborted calls
+   * throw an {@link CdpError} with `code === "aborted"`.
+   */
+  send<T = unknown>(
+    method: string,
+    params?: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): Promise<T>;
+
+  /**
+   * Release any backend-side resources (CDP sessions, in-flight
+   * requests, listeners). Idempotent. Calling `send` after `dispose`
+   * is allowed but should surface as an error.
+   */
+  dispose(): void;
+}
+
+/**
+ * Backend kind exposed by a concrete CdpClient. Used by tools that
+ * want to branch on the transport (e.g. browser_navigate should skip
+ * the sacrificial-profile screencast setup when running against the
+ * user's own Chrome via the extension).
+ */
+export type CdpClientKind = "local" | "extension" | "cdp-inspect";
+
+/**
+ * Backend mode preference for the CDP factory. Controls which
+ * transport is selected:
+ *
+ *  - `"auto"` — default, existing priority-ordered fallback
+ *    (extension → cdp-inspect → local).
+ *  - `"extension"` — pin to the chrome-extension backend. Fails
+ *    immediately if the host browser proxy is unavailable.
+ *  - `"cdp-inspect"` — pin to the cdp-inspect backend. Fails
+ *    immediately if cdp-inspect cannot connect.
+ *  - `"local"` — pin to the local Playwright backend. No fallback.
+ */
+export type BrowserMode = "auto" | "extension" | "cdp-inspect" | "local";
+
+/**
+ * Stage at which a candidate attempt ended. Used in
+ * {@link AttemptDiagnostic} to indicate how far the attempt progressed.
+ */
+export type AttemptStage =
+  | "candidate_selection" // failed before construction (precondition not met)
+  | "construction" // create() threw
+  | "send" // manager.send() threw or returned an error envelope
+  | "success"; // command completed successfully
+
+/**
+ * Structured diagnostic for a single candidate attempt during the
+ * factory's failover walk. Collected into an array and attached to
+ * thrown {@link CdpError} instances so higher layers can render
+ * detailed failure information in user-facing tool errors.
+ */
+export interface AttemptDiagnostic {
+  /** Which backend kind was attempted. */
+  readonly candidateKind: CdpClientKind;
+  /** Why this candidate was included (from {@link BackendCandidate.reason}). */
+  readonly inclusionReason: string;
+  /** How far the attempt progressed before it ended. */
+  readonly stage: AttemptStage;
+  /** Error code from the CdpError, if the attempt failed. */
+  readonly errorCode?: string;
+  /** Error message from the CdpError, if the attempt failed. */
+  readonly errorMessage?: string;
+  /** Discovery-level error code extracted from the underlying error, if any. */
+  readonly discoveryCode?: string;
+}
+
+/**
+ * Concrete CdpClient instance returned by the factory. Carries the
+ * backend `kind` for transport-aware branches in tool code.
+ */
+export interface ScopedCdpClient extends CdpClient {
+  readonly kind: CdpClientKind;
+  /** Stable conversation id this client is bound to. */
+  readonly conversationId: string;
+}
+
+/**
+ * A deferred backend candidate used by the chained factory. Each
+ * candidate carries a `kind` label and a `create` thunk that
+ * materialises the underlying {@link CdpClient} + {@link BrowserBackend}
+ * on demand. The factory only calls `create()` when the candidate is
+ * actually selected (either as the primary or as a failover target),
+ * so backends that are never reached pay zero setup cost.
+ */
+export interface BackendCandidate {
+  readonly kind: CdpClientKind;
+  /** Human-readable reason this candidate was included. */
+  readonly reason: string;
+  /**
+   * Materialise the backend. Called at most once — the factory caches
+   * the result after the first successful CDP command so subsequent
+   * commands reuse the same backend (sticky semantics).
+   */
+  create(): {
+    client: CdpClient;
+    backend: import("../../../browser-session/types.js").BrowserBackend;
+  };
+}

package/src/tools/credentials/vault.ts

@@ -1,5 +1,6 @@
 import { getConfig } from "../../config/loader.js";
 import {
+  clearSlackUserToken,
   setSlackChannelConfig,
   type SlackChannelConfigResult,
 } from "../../daemon/handlers/config-slack-channel.js";
@@ -37,20 +38,26 @@ const log = getLogger("credential-vault");
 function isSlackChannelCredential(
   service: string,
   field: string,
-): field is "bot_token" | "app_token" {
+): field is "bot_token" | "app_token" | "user_token" {
   return (
     service === "slack_channel" &&
-    (field === "bot_token" || field === "app_token")
+    (field === "bot_token" ||
+      field === "app_token" ||
+      field === "user_token")
   );
 }
 
 async function storeSlackChannelCredential(
-  field: "bot_token" | "app_token",
+  field: "bot_token" | "app_token" | "user_token",
   value: string,
 ): Promise<SlackChannelConfigResult> {
-  return field === "bot_token"
-    ? setSlackChannelConfig(value, undefined)
-    : setSlackChannelConfig(undefined, value);
+  if (field === "bot_token") {
+    return setSlackChannelConfig(value, undefined);
+  }
+  if (field === "app_token") {
+    return setSlackChannelConfig(undefined, value);
+  }
+  return setSlackChannelConfig(undefined, undefined, value);
 }
 
 function formatSlackChannelStatus(result: SlackChannelConfigResult): string {
@@ -457,6 +464,28 @@ class CredentialStoreTool implements Tool {
           };
         }
 
+        // Surgical delete for the Slack user_token: it grants read-only access
+        // to channels the bot isn't a member of, but the Socket Mode connection
+        // is powered by the bot + app tokens. Tearing down the oauth_connection
+        // row when only user_token is removed would flap the integration's
+        // connected state until the next sync. Keep bot+app teardown behavior
+        // unchanged — those tokens are what the connection depends on.
+        if (service === "slack_channel" && field === "user_token") {
+          const slackResult = await clearSlackUserToken();
+          if (!slackResult.success) {
+            return {
+              content: `Error: ${
+                slackResult.error ?? "failed to delete Slack user token"
+              }`,
+              isError: true,
+            };
+          }
+          return {
+            content: `Deleted credential for ${service}/${field}.`,
+            isError: false,
+          };
+        }
+
         const key = credentialKey(service, field);
         const result = await deleteSecureKeyAsync(key);
         if (result === "error") {

package/src/tools/filesystem/edit.ts

@@ -9,7 +9,7 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 class FileEditTool implements Tool {
   name = "file_edit";
   description =
-    "Replace an exact string in a file with a new string. Use this for surgical edits instead of rewriting entire files. To delete a file, use bash with rm instead.";
+    "Replace an exact string in a file on your own machine with a new string. Use this for surgical edits instead of rewriting entire files. Use host_file_edit for files on your guardian's device instead.";
   category = "filesystem";
   defaultRiskLevel = RiskLevel.Low;
 

package/src/tools/filesystem/list.ts

@@ -8,7 +8,7 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 class FileListTool implements Tool {
   name = "file_list";
   description =
-    "List the contents of a directory. Returns file and subdirectory names with type indicators and sizes.";
+    "List the contents of a directory on your own machine. Returns file and subdirectory names with type indicators and sizes.";
   category = "filesystem";
   defaultRiskLevel = RiskLevel.Low;
 

package/src/tools/filesystem/read.ts

@@ -14,7 +14,7 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 class FileReadTool implements Tool {
   name = "file_read";
   description =
-    "Read the contents of a file. For image files (JPEG, PNG, GIF, WebP), returns the image for visual analysis. Always use this tool (not host_file_read) for workspace files under .vellum.";
+    "Read the contents of a file on your own machine. For image files (JPEG, PNG, GIF, WebP), returns the image for visual analysis. Use host_file_read for files on your guardian's device instead.";
   category = "filesystem";
   defaultRiskLevel = RiskLevel.Low;
 

package/src/tools/filesystem/write.ts

@@ -8,7 +8,8 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
 class FileWriteTool implements Tool {
   name = "file_write";
-  description = "Write content to a file, creating it if it does not exist";
+  description =
+    "Write content to a file on your own machine, creating it if it does not exist. Use host_file_write for files on your guardian's device instead.";
   category = "filesystem";
   defaultRiskLevel = RiskLevel.Low;
 

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

@@ -8,7 +8,7 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 class HostFileEditTool implements Tool {
   name = "host_file_edit";
   description =
-    "Replace exact text in a host filesystem file with new text. Not for workspace files under .vellum (use file_edit instead).";
+    "Replace exact text in a file on your guardian's device with new text. For files on your own machine, use file_edit instead.";
   category = "host-filesystem";
   defaultRiskLevel = RiskLevel.Medium;
 

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

@@ -13,7 +13,7 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 class HostFileReadTool implements Tool {
   name = "host_file_read";
   description =
-    "Read the contents of a file on the host filesystem, including images (JPEG, PNG, GIF, WebP). Not for workspace files under .vellum (use file_read instead).";
+    "Read the contents of a file on your guardian's device, including images (JPEG, PNG, GIF, WebP). For files on your own machine, use file_read instead.";
   category = "host-filesystem";
   defaultRiskLevel = RiskLevel.Medium;
 
@@ -54,21 +54,9 @@ class HostFileReadTool implements Tool {
       };
     }
 
-    // Image files must be handled locally — the host-file proxy protocol
-    // only carries {content, isError} and cannot transport contentBlocks
-    // (base64 image data). Check for image extensions before the proxy
-    // short-circuit so image reads work in managed/macOS+iOS sessions.
-    const ext = extname(rawPath).toLowerCase();
-    if (IMAGE_EXTENSIONS.has(ext)) {
-      const pathCheck = hostPolicy(rawPath);
-      if (!pathCheck.ok) {
-        return { content: `Error: ${pathCheck.error}`, isError: true };
-      }
-      return readImageFile(pathCheck.resolved);
-    }
-
     // Proxy to connected client for execution on the user's machine
-    // when a capable client is available (managed/cloud-hosted mode).
+    // when a capable client is available (managed/cloud-hosted mode),
+    // including image reads that need the host filesystem view.
     if (context.hostFileProxy?.isAvailable()) {
       return context.hostFileProxy.request(
         {
@@ -82,6 +70,15 @@ class HostFileReadTool implements Tool {
       );
     }
 
+    const ext = extname(rawPath).toLowerCase();
+    if (IMAGE_EXTENSIONS.has(ext)) {
+      const pathCheck = hostPolicy(rawPath);
+      if (!pathCheck.ok) {
+        return { content: `Error: ${pathCheck.error}`, isError: true };
+      }
+      return readImageFile(pathCheck.resolved);
+    }
+
     const ops = new FileSystemOps(hostPolicy);
 
     const result = ops.readFileSafe({

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

@@ -8,7 +8,7 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 class HostFileWriteTool implements Tool {
   name = "host_file_write";
   description =
-    "Write content to a file on the host filesystem, creating it if it does not exist. Not for workspace files under .vellum (use file_write instead).";
+    "Write content to a file on your guardian's device, creating it if it does not exist. For files on your own machine, use file_write instead.";
   category = "host-filesystem";
   defaultRiskLevel = RiskLevel.Medium;
 

package/src/tools/host-terminal/host-shell.ts

@@ -207,30 +207,35 @@ class HostShellTool implements Tool {
         detached: true,
       });
 
-      const timer = setTimeout(() => {
-        timedOut = true;
+      // Kill the entire process tree. Tries the process group first
+      // (negative PID), then falls back to killing the direct child if the
+      // PID is unavailable or the group kill fails.
+      const killTree = () => {
+        if (child.pid != null) {
+          try {
+            process.kill(-child.pid, "SIGKILL");
+            return;
+          } catch {
+            // Process group may have already exited — fall through.
+          }
+        }
         try {
-          process.kill(-child.pid!, "SIGKILL");
+          child.kill("SIGKILL");
         } catch {
-          // Process group may have already exited.
+          // Child may have already exited.
         }
+      };
+
+      const timer = setTimeout(() => {
+        timedOut = true;
+        killTree();
       }, timeoutMs);
 
       // Cooperative cancellation via AbortSignal
-      const onAbort = () => {
-        try {
-          process.kill(-child.pid!, "SIGKILL");
-        } catch {
-          // Process group may have already exited.
-        }
-      };
+      const onAbort = () => killTree();
       if (context.signal) {
         if (context.signal.aborted) {
-          try {
-            process.kill(-child.pid!, "SIGKILL");
-          } catch {
-            // Process group may have already exited.
-          }
+          killTree();
         } else {
           context.signal.addEventListener("abort", onAbort, { once: true });
         }

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

@@ -8,6 +8,7 @@ import { Readable } from "node:stream";
 import { RiskLevel } from "../../permissions/types.js";
 import type { ToolDefinition } from "../../providers/types.js";
 import { getLogger } from "../../util/logger.js";
+import { safeStringSlice } from "../../util/unicode.js";
 import { registerTool } from "../registry.js";
 import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 import {
@@ -357,11 +358,13 @@ function extractHtmlMetadata(html: string): {
   // regex backtracking on large HTML documents.
   // Strip <script> blocks first so that a literal "</head>" inside a script
   // doesn't cause a false match that truncates the search region prematurely.
-  const candidate = html.slice(0, 200_000);
+  const candidate = safeStringSlice(html, 0, 200_000);
   const stripped = candidate.replace(/<script[\s>][\s\S]*?<\/script>/gi, "");
   const headEnd = stripped.search(/<\/head[\s>]/i);
   const searchRegion =
-    headEnd >= 0 ? stripped.slice(0, headEnd + 10) : stripped.slice(0, 50_000);
+    headEnd >= 0
+      ? safeStringSlice(stripped, 0, headEnd + 10)
+      : safeStringSlice(stripped, 0, 50_000);
 
   const title = extractFirstMatch(
     searchRegion,

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

@@ -61,6 +61,9 @@ async function getApiKey(
   return (await getProviderKeyAsync("perplexity")) ?? undefined;
 }
 
+const CITATION_INSTRUCTION =
+  "\n\nWhen presenting these results, cite sources as inline markdown hyperlinks next to the claims they support (e.g., 'according to [Source Title](url)'). Do not list references separately at the end.";
+
 function formatBraveResults(
   results: BraveSearchResult[],
   query: string,
@@ -89,7 +92,7 @@ function formatBraveResults(
     lines.push("");
   }
 
-  return lines.join("\n");
+  return lines.join("\n") + CITATION_INSTRUCTION;
 }
 
 function formatPerplexityResults(
@@ -111,7 +114,7 @@ function formatPerplexityResults(
     }
   }
 
-  return lines.join("\n");
+  return lines.join("\n") + CITATION_INSTRUCTION;
 }
 
 async function executeBraveSearch(