@vellumai/assistant 0.6.3 → 0.6.4

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

@@ -9,6 +9,20 @@ export {
   createExtensionCdpClient,
   ExtensionCdpClient,
 } from "./extension-cdp-client.js";
-export { getCdpClient } from "./factory.js";
+export {
+  buildCandidateList,
+  buildChainedClient,
+  buildPinnedCandidateList,
+  getCdpClient,
+  type GetCdpClientOptions,
+} from "./factory.js";
 export { createLocalCdpClient, LocalCdpClient } from "./local-cdp-client.js";
-export type { CdpClient, CdpClientKind, ScopedCdpClient } from "./types.js";
+export type {
+  AttemptDiagnostic,
+  AttemptStage,
+  BackendCandidate,
+  BrowserMode,
+  CdpClient,
+  CdpClientKind,
+  ScopedCdpClient,
+} from "./types.js";

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

@@ -41,6 +41,51 @@ export interface CdpClient {
  */
 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.
@@ -50,3 +95,26 @@ export interface ScopedCdpClient extends CdpClient {
   /** 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/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(

package/src/tools/shared/shell-output.ts

@@ -3,6 +3,8 @@ import { unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
+import { safeStringSlice } from "../../util/unicode.js";
+
 export const MAX_OUTPUT_LENGTH = 20_000;
 
 /** Tracks temp files created for truncated shell output so they can be cleaned up on shutdown. */
@@ -63,7 +65,7 @@ export function formatShellOutput(
     }
     const fileAttr = fullOutputPath ? ` file="${fullOutputPath}"` : "";
     const msg = `<output_truncated limit="20K"${fileAttr} />`;
-    output = output.slice(0, MAX_OUTPUT_LENGTH) + `\n${msg}`;
+    output = safeStringSlice(output, 0, MAX_OUTPUT_LENGTH) + `\n${msg}`;
     statusParts.push(msg);
   }
 

package/src/tools/side-effects.ts

@@ -20,6 +20,8 @@ const SIDE_EFFECT_TOOLS: ReadonlySet<string> = new Set([
   "browser_select_option",
   "browser_hover",
   "browser_close",
+  "browser_attach",
+  "browser_detach",
   "browser_fill_credential",
   "document_create",
   "document_update",

package/src/tools/skills/sandbox-runner.ts

@@ -4,6 +4,7 @@ import { mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 
 import { computeSkillVersionHash } from "../../skills/version-hash.js";
+import { safeStringSlice } from "../../util/unicode.js";
 import { buildSanitizedEnv } from "../terminal/safe-env.js";
 import { wrapCommand } from "../terminal/sandbox.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
@@ -218,7 +219,7 @@ function spawnRunner(
       if (code !== 0) {
         const truncatedStderr =
           stderr.length > MAX_OUTPUT_CHARS
-            ? stderr.slice(0, MAX_OUTPUT_CHARS) + "\n[stderr truncated]"
+            ? safeStringSlice(stderr, 0, MAX_OUTPUT_CHARS) + "\n[stderr truncated]"
             : stderr;
         resolve({
           content: `Skill tool script "${executorPath}" exited with code ${code}:\n${truncatedStderr}`,
@@ -229,7 +230,7 @@ function spawnRunner(
 
       const truncatedStdout =
         stdout.length > MAX_OUTPUT_CHARS
-          ? stdout.slice(0, MAX_OUTPUT_CHARS) + "\n[stdout truncated]"
+          ? safeStringSlice(stdout, 0, MAX_OUTPUT_CHARS) + "\n[stdout truncated]"
           : stdout;
       resolve({ content: truncatedStdout, isError: false });
     });

package/src/tools/terminal/safe-env.ts

@@ -28,10 +28,13 @@ export const SAFE_ENV_VARS = [
   "GPG_TTY",
   "GNUPGHOME",
   "VELLUM_DEV",
+  "VELLUM_DEBUG",
+  "VELLUM_ENVIRONMENT",
   "VELLUM_WORKSPACE_DIR",
   "CES_BOOTSTRAP_SOCKET_DIR",
   "GATEWAY_INTERNAL_URL",
   "VELLUM_PLATFORM_URL",
+  "VELLUM_ASSISTANT_PLATFORM_URL",
   "VELLUM_DOCS_BASE_URL",
   "CES_CREDENTIAL_URL",
   "CES_MANAGED_MODE",
@@ -45,6 +48,8 @@ export const SAFE_ENV_VARS = [
   "VELLUM_PROFILER_MIN_FREE_MB",
   "VELLUM_MEMORY_LIMIT",
   "VELLUM_CPU_LIMIT",
+  "VELLUM_BACKUP_DIR",
+  "VELLUM_BACKUP_KEY_PATH",
 ] as const;
 
 /**
@@ -76,7 +81,10 @@ export function buildSanitizedEnv(): Record<string, string> {
   env.VELLUM_WORKSPACE_DIR = getWorkspaceDir();
   // Ensure UTF-8 locale so multi-byte characters (em dashes, curly quotes,
   // arrows, etc.) survive piping through tools like pbcopy without corruption.
-  if (!env.LANG) env.LANG = "C.UTF-8";
-  if (!env.LC_ALL) env.LC_ALL = "C.UTF-8";
+  // macOS (Darwin) does not provide C.UTF-8, so use en_US.UTF-8 there.
+  const utf8Locale =
+    process.platform === "darwin" ? "en_US.UTF-8" : "C.UTF-8";
+  if (!env.LANG) env.LANG = utf8Locale;
+  if (!env.LC_ALL) env.LC_ALL = utf8Locale;
   return env;
 }

package/src/tools/terminal/shell.ts

@@ -9,7 +9,11 @@ import type { ToolDefinition } from "../../providers/types.js";
 import { isUntrustedTrustClass } from "../../runtime/actor-trust-resolver.js";
 import { redactSecrets } from "../../security/secret-scanner.js";
 import { getLogger } from "../../util/logger.js";
-import { getDataDir, getWorkspaceDir } from "../../util/platform.js";
+import {
+  getDataDir,
+  getProtectedDir,
+  getWorkspaceDir,
+} from "../../util/platform.js";
 import { resolveCredentialRef } from "../credentials/resolve.js";
 import {
   getOrStartSession,
@@ -46,9 +50,16 @@ function buildCredentialRefTrace(
  * - CES managed-mode data root (CES_DATA_DIR, or /ces-data when CES_MANAGED_MODE is set)
  */
 function buildCesProtectedPaths(): string[] {
-  const securityDir =
-    process.env.GATEWAY_SECURITY_DIR || join(homedir(), ".vellum", "protected");
-  const paths = [securityDir, join(getWorkspaceDir(), "data", "db")];
+  // Block both the legacy global protected dir and the current per-instance
+  // protected dir so the sandbox read-block works in both single-instance
+  // and multi-instance setups. In the default case (no BASE_DATA_DIR) the
+  // two entries collapse via the Set dedupe.
+  const protectedDirs = process.env.GATEWAY_SECURITY_DIR
+    ? [process.env.GATEWAY_SECURITY_DIR]
+    : Array.from(
+        new Set([join(homedir(), ".vellum", "protected"), getProtectedDir()]),
+      );
+  const paths = [...protectedDirs, join(getWorkspaceDir(), "data", "db")];
 
   // CES bootstrap socket directory - block access to the Unix socket that
   // accepts RPC commands from the assistant process.

package/src/tools/tool-manifest.ts

@@ -29,6 +29,24 @@ import { requestSystemPermissionTool } from "./system/request-permission.js";
 import { shellTool } from "./terminal/shell.js";
 import type { Tool } from "./types.js";
 
+// ── External tool registry ───────────────────────────────────────────
+// Skills register their tools here at initialization time so the tool
+// manifest can include them without importing from `../skills/`.
+const externalTools: Tool[] = [];
+
+/**
+ * Register tools provided by an external skill. Called during skill
+ * initialization.
+ */
+export function registerExternalTools(tools: Tool[]): void {
+  externalTools.push(...tools);
+}
+
+/** Return all externally registered tools. */
+export function getExternalTools(): Tool[] {
+  return [...externalTools];
+}
+
 // ── Eager side-effect modules ───────────────────────────────────────
 // These static imports trigger top-level `registerTool()` side effects on
 // first evaluation. The named imports above serve double duty: they give us
@@ -91,6 +109,9 @@ export const explicitTools: Tool[] = [
   recallTool,
   credentialStoreTool,
   notifyParentTool,
+  // Meet tools are registered via registerExternalTools() during skill
+  // initialization — the assistant never imports directly from skills/.
+  ...getExternalTools(),
 ];
 
 // ── CES tools (feature-flag gated) ──────────────────────────────────

package/src/tools/types.ts

@@ -1,5 +1,6 @@
 import type { ApprovalRequired } from "@vellumai/ces-contracts";
 
+import type { InterfaceId } from "../channels/types.js";
 import type { CesClient } from "../credential-execution/client.js";
 import type { SecretPromptResult } from "../permissions/secret-prompter.js";
 import type {
@@ -162,6 +163,14 @@ export interface ToolContext {
   callSessionId?: string;
   /** True when the tool invocation was triggered by a user clicking a surface action button (not a regular message). */
   triggeredBySurfaceAction?: boolean;
+  /**
+   * True when the invocation is inside a scheduled task run whose
+   * `required_tools` array pre-authorized this tool at task-creation time.
+   * Tools that normally require a surface-action click (e.g. bulk archive,
+   * unsubscribe) may treat this as equivalent consent, since the user
+   * already reviewed the tool list when the task was saved.
+   */
+  batchAuthorizedByTask?: boolean;
   /** External user ID of the requester (non-guardian actor). Used for scoped grant consumption. */
   requesterExternalUserId?: string;
   /** Chat ID of the requester (non-guardian actor). Used for tool grant request escalation notifications. */
@@ -184,6 +193,14 @@ export interface ToolContext {
   isPlatformHosted?: boolean;
   /** CES RPC client for credential execution operations. When present, the executor can bridge CES approval flows. */
   cesClient?: CesClient;
+  /**
+   * The interface ID of the connected client driving the current turn (e.g.
+   * "macos", "chrome-extension"). Browser backend policy uses this to decide
+   * transport preference — for example, macOS-originated turns prefer the
+   * user's real Chrome session via the paired extension before falling back
+   * to cdp-inspect or local Playwright.
+   */
+  transportInterface?: InterfaceId;
 }
 
 export interface DiffInfo {

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

@@ -31,7 +31,7 @@ export const uiShowTool: Tool = {
     "Show structured data or UI to the user. For long-form writing use the document skill; for interactive apps use the app-builder skill.\n\n" +
     "Surface types (data shapes):\n" +
     '- card: { title, subtitle?, body, metadata?: [{ label, value }], template?, templateData? }. Templates: "weather_forecast" (native weather widget), "task_progress" (live step tracker - update via ui_update on data.templateData; shape: { title, status: "in_progress"|"completed"|"failed", steps: [{ label, status: "pending"|"in_progress"|"completed"|"failed", detail? }] })\n' +
-    '- table: { columns: [{ id, label, width? }], rows: [{ id, cells: Record<id, string | { text, icon?, iconColor?: "success"|"warning"|"error"|"muted" }>, selectable?, selected? }], selectionMode?: "none"|"single"|"multiple", caption? }\n' +
+    '- table: { columns: [{ id, label }], rows: [{ id, cells: Record<id, string | { text, icon?, iconColor?: "success"|"warning"|"error"|"muted" }>, selectable?, selected? }], selectionMode?: "none"|"single"|"multiple", caption? }\n' +
     '- form: { description?, fields: [{ id, type: "text"|"textarea"|"select"|"toggle"|"number"|"password", label, placeholder?, required?, defaultValue?, options?: [{ label, value }] }], submitLabel? }. Multi-page: { pages: [{ id, title, description?, fields }], pageLabels?: { next?, back?, submit? }, submitLabel? }\n' +
     '- list: { items: [{ id, title, subtitle?, icon?, selected? }], selectionMode: "single"|"multiple"|"none" }\n' +
     "- confirmation: { message, detail?, confirmLabel?, confirmedLabel?, cancelLabel?, destructive? }\n" +
@@ -98,6 +98,11 @@ export const uiShowTool: Tool = {
             description:
               "Whether to block until the user interacts with an action. Defaults to true when actions are provided.",
           },
+          persistent: {
+            type: "boolean",
+            description:
+              "When true, clicking an action does not dismiss the surface — the card stays visible and only the clicked action is marked as spent. Use for launcher or menu-style cards where the user may click multiple buttons. Defaults to false.",
+          },
         },
         required: ["surface_type", "data"],
       },