@vellumai/assistant 0.3.19 → 0.3.20

package/src/tools/terminal/sandbox-diagnostics.ts

@@ -1,9 +1,8 @@
-import { execFileSync,execSync } from 'node:child_process';
+import { execSync } from 'node:child_process';
 
 import { getConfig } from '../../config/loader.js';
 import type { SandboxConfig } from '../../config/schema.js';
-import { getSandboxWorkingDir,isLinux, isMacOS } from '../../util/platform.js';
-import { DEFAULT_SANDBOX_IMAGE } from './backends/docker.js';
+import { isLinux, isMacOS } from '../../util/platform.js';
 
 export interface SandboxCheckResult {
   label: string;
@@ -14,73 +13,12 @@ export interface SandboxCheckResult {
 export interface SandboxDiagnostics {
   config: {
     enabled: boolean;
-    backend: string;
-    dockerImage: string;
   };
   /** Why the active backend was selected (config vs platform default). */
   activeBackendReason: string;
   checks: SandboxCheckResult[];
 }
 
-function checkDockerCli(): SandboxCheckResult {
-  try {
-    const out = execSync('docker --version', { stdio: 'pipe', timeout: 5000, encoding: 'utf-8' }).trim();
-    return { label: 'Docker CLI installed', ok: true, detail: out };
-  } catch {
-    return { label: 'Docker CLI installed', ok: false, detail: 'docker not found in PATH' };
-  }
-}
-
-function checkDockerDaemon(): SandboxCheckResult {
-  try {
-    execSync('docker info', { stdio: 'pipe', timeout: 10000 });
-    return { label: 'Docker daemon running', ok: true };
-  } catch {
-    return { label: 'Docker daemon running', ok: false, detail: 'daemon not reachable — start Docker Desktop or run "sudo systemctl start docker"' };
-  }
-}
-
-function checkDockerImage(image: string): SandboxCheckResult {
-  try {
-    execFileSync('docker', ['image', 'inspect', image], { stdio: 'pipe', timeout: 10000 });
-    return { label: `Docker image available (${image})`, ok: true };
-  } catch {
-    // The default sandbox image is built locally from Dockerfile.sandbox — docker pull won't work.
-    const remediation = image === DEFAULT_SANDBOX_IMAGE
-      ? 'build with: docker build --no-cache -t vellum-sandbox:latest -f assistant/Dockerfile.sandbox assistant'
-      : `pull with: docker pull ${image}`;
-    return { label: `Docker image available (${image})`, ok: false, detail: remediation };
-  }
-}
-
-function checkDockerMountProbe(image: string): SandboxCheckResult {
-  // Use the same sandbox path and writable-mount probe that the runtime
-  // preflight uses (checkMountProbe in docker.ts) so doctor validates
-  // exactly what runtime enforces.
-  const sandboxRoot = getSandboxWorkingDir();
-  try {
-    execFileSync(
-      'docker',
-      [
-        'run', '--rm',
-        '--mount', `type=bind,src=${sandboxRoot},dst=/workspace`,
-        image, 'test', '-w', '/workspace',
-      ],
-      { stdio: 'pipe', timeout: 15000 },
-    );
-    return { label: 'Docker mount writable', ok: true };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : 'unknown error';
-    return {
-      label: 'Docker mount writable',
-      ok: false,
-      detail: 'Cannot bind-mount sandbox root or /workspace is not writable. ' +
-        'If using Docker Desktop, enable file sharing for this path in Settings > Resources > File Sharing. ' +
-        `(${msg})`,
-    };
-  }
-}
-
 function checkNativeBackend(): SandboxCheckResult {
   if (isMacOS()) {
     try {
@@ -105,15 +43,12 @@ function getActiveBackendReason(sandboxConfig: SandboxConfig): string {
   if (!sandboxConfig.enabled) {
     return 'Sandbox is disabled in configuration';
   }
-  if (sandboxConfig.backend === 'docker') {
-    return 'Docker backend selected in configuration (sandbox.backend = "docker")';
-  }
-  return 'Native backend selected in configuration (sandbox.backend = "native")';
+  return 'Native backend selected';
 }
 
 /**
- * Run sandbox backend diagnostics. Checks Docker availability,
- * native backend availability, and reports current configuration.
+ * Run sandbox backend diagnostics. Checks native backend availability
+ * and reports current configuration.
  */
 export function runSandboxDiagnostics(): SandboxDiagnostics {
   const config = getConfig();
@@ -121,28 +56,12 @@ export function runSandboxDiagnostics(): SandboxDiagnostics {
 
   const checks: SandboxCheckResult[] = [];
 
-  // Always check native backend availability as a diagnostic signal
+  // Check native backend availability
   checks.push(checkNativeBackend());
 
-  // Docker checks: CLI, daemon, image, container execution
-  const cliResult = checkDockerCli();
-  checks.push(cliResult);
-
-  if (cliResult.ok) {
-    const daemonResult = checkDockerDaemon();
-    checks.push(daemonResult);
-
-    if (daemonResult.ok) {
-      checks.push(checkDockerImage(sandboxConfig.docker.image));
-      checks.push(checkDockerMountProbe(sandboxConfig.docker.image));
-    }
-  }
-
   return {
     config: {
       enabled: sandboxConfig.enabled,
-      backend: sandboxConfig.backend,
-      dockerImage: sandboxConfig.docker.image,
     },
     activeBackendReason: getActiveBackendReason(sandboxConfig),
     checks,

package/src/tools/terminal/sandbox.ts

@@ -1,6 +1,4 @@
 import type { SandboxConfig } from '../../config/schema.js';
-import { getSandboxWorkingDir } from '../../util/platform.js';
-import { DockerBackend } from './backends/docker.js';
 import { NativeBackend } from './backends/native.js';
 import type { SandboxResult, WrapOptions } from './backends/types.js';
 
@@ -12,7 +10,7 @@ const nativeBackend = new NativeBackend();
  * Wrap a shell command for sandboxed execution.
  *
  * When sandboxing is disabled, returns a plain bash invocation.
- * When enabled, delegates to the configured backend (native or docker).
+ * When enabled, delegates to the native backend.
  * Fails closed if the backend cannot be applied.
  *
  * @param options  Per-invocation overrides (e.g. networkMode for proxied bash).
@@ -31,14 +29,5 @@ export function wrapCommand(
     };
   }
 
-  if (config.backend === 'docker') {
-    // Always mount the canonical sandbox fs root, not whatever workingDir
-    // happens to be. workingDir may be a subdirectory; the mount source
-    // must be the fixed root so the entire sandbox filesystem is available.
-    const sandboxRoot = getSandboxWorkingDir();
-    const backend = new DockerBackend(sandboxRoot, config.docker);
-    return backend.wrap(command, workingDir, options);
-  }
-
   return nativeBackend.wrap(command, workingDir, options);
 }

package/src/tools/terminal/shell.ts

@@ -1,5 +1,4 @@
-import { execSync,spawn } from 'node:child_process';
-import { platform } from 'node:os';
+import { spawn } from 'node:child_process';
 
 import { getConfig } from '../../config/loader.js';
 import { RiskLevel } from '../../permissions/types.js';
@@ -21,32 +20,6 @@ import { wrapCommand } from './sandbox.js';
 
 const log = getLogger('shell-tool');
 
-/**
- * Returns the host address to bind the proxy to when Docker sandbox is active.
- * On macOS, Docker Desktop routes host.docker.internal through the VM to
- * 127.0.0.1, so no bind change is needed. On Linux, we need to bind to the
- * Docker bridge gateway IP so containers can reach the proxy.
- */
-function getDockerProxyHost(): string {
-  if (platform() !== 'linux') return '127.0.0.1';
-
-  try {
-    // Docker bridge gateway is the default route from inside docker0 network.
-    // `ip -4 addr show docker0` outputs the gateway IP assigned to the bridge.
-    const output = execSync('ip -4 addr show docker0 2>/dev/null', { encoding: 'utf-8' });
-    const match = output.match(/inet\s+(\d+\.\d+\.\d+\.\d+)/);
-    if (match) return match[1];
-  } catch {
-    // docker0 interface may not exist (e.g. rootless Docker, custom networks)
-  }
-  // Fallback: bind to localhost when docker0 is unavailable (e.g. rootless
-  // Docker, custom networks). This avoids EADDRNOTAVAIL from 172.17.0.1 while
-  // keeping the proxy off public interfaces — 0.0.0.0 would expose the
-  // unauthenticated credential proxy to the network. Docker containers won't
-  // be able to reach localhost on the host, but that's a safer failure mode.
-  return '127.0.0.1';
-}
-
 class ShellTool implements Tool {
   name = 'bash';
   description = 'Execute a shell command on the local machine';
@@ -153,7 +126,6 @@ class ShellTool implements Tool {
     const sandboxConfig = context.sandboxOverride != null
       ? { ...config.sandbox, enabled: context.sandboxOverride }
       : config.sandbox;
-    const isDockerSandbox = sandboxConfig.enabled && sandboxConfig.backend === 'docker';
 
     // Acquire proxy session if proxied mode is requested.
     // `getOrStartSession` serializes per-conversation so concurrent proxied
@@ -170,9 +142,9 @@ class ShellTool implements Tool {
           undefined,
           getDataDir(),
           context.proxyApprovalCallback,
-          isDockerSandbox ? { listenHost: getDockerProxyHost() } : undefined,
+          undefined,
         );
-        proxyEnv = getSessionEnv(session.id, { dockerMode: isDockerSandbox });
+        proxyEnv = getSessionEnv(session.id);
       } catch (err) {
         log.error({ err }, 'Failed to start proxy session');
         return {

package/src/tools/tool-approval-handler.ts

@@ -1,14 +1,42 @@
+import { consumeGrantForInvocation } from '../approvals/approval-primitive.js';
 import { isToolBlocked } from '../security/parental-control-store.js';
+import { computeToolApprovalDigest } from '../security/tool-approval-digest.js';
 import { getTaskRunRules } from '../tasks/ephemeral-permissions.js';
 import { getLogger } from '../util/logger.js';
 import { enforceGuardianOnlyPolicy } from './guardian-control-plane-policy.js';
 import { getAllTools, getTool } from './registry.js';
+import { isSideEffectTool } from './side-effects.js';
 import type { ExecutionTarget, Tool, ToolContext, ToolExecutionResult, ToolLifecycleEvent } from './types.js';
 
 const log = getLogger('tool-approval-handler');
 
+function isUntrustedGuardianActorRole(role: ToolContext['guardianActorRole']): boolean {
+  return role === 'non-guardian' || role === 'unverified_channel';
+}
+
+function requiresGuardianApprovalForActor(
+  toolName: string,
+  input: Record<string, unknown>,
+  executionTarget: ExecutionTarget,
+): boolean {
+  // Side-effect tools always require guardian approval for untrusted actors.
+  // Read-only host execution is also blocked because it can leak sensitive
+  // local information (e.g. shell/file reads).
+  return isSideEffectTool(toolName, input) || executionTarget === 'host';
+}
+
+function guardianApprovalDeniedMessage(
+  actorRole: ToolContext['guardianActorRole'],
+  toolName: string,
+): string {
+  if (actorRole === 'unverified_channel') {
+    return `Permission denied for "${toolName}": this action requires guardian approval from a verified channel identity.`;
+  }
+  return `Permission denied for "${toolName}": this action requires guardian approval and the current actor is not the guardian.`;
+}
+
 export type PreExecutionGateResult =
-  | { allowed: true; tool: Tool }
+  | { allowed: true; tool: Tool; grantConsumed?: boolean }
   | { allowed: false; result: ToolExecutionResult };
 
 /**
@@ -22,7 +50,7 @@ export class ToolApprovalHandler {
    * Returns the resolved Tool if all gates pass, or an early-return
    * ToolExecutionResult if any gate blocks execution.
    */
-  checkPreExecutionGates(
+  async checkPreExecutionGates(
     name: string,
     input: Record<string, unknown>,
     context: ToolContext,
@@ -30,7 +58,7 @@ export class ToolApprovalHandler {
     riskLevel: string,
     startTime: number,
     emitLifecycleEvent: (event: ToolLifecycleEvent) => void,
-  ): PreExecutionGateResult {
+  ): Promise<PreExecutionGateResult> {
     // Bail out immediately if the session was aborted before this tool started.
     if (context.signal?.aborted) {
       const durationMs = Date.now() - startTime;
@@ -111,6 +139,33 @@ export class ToolApprovalHandler {
       return { allowed: false, result: { content: guardianCheck.reason!, isError: true } };
     }
 
+    // Determine whether this invocation requires a scoped grant. Capture
+    // the consume params now but defer the actual atomic consumption until
+    // after all downstream policy gates (allowedToolNames, task-run
+    // preflight, tool registry) pass. This prevents wasting a one-time-use
+    // grant when a subsequent gate rejects the invocation.
+    let needsGrantConsumption = false;
+    let deferredConsumeParams: Parameters<typeof consumeGrantForInvocation>[0] | null = null;
+
+    if (
+      isUntrustedGuardianActorRole(context.guardianActorRole)
+      && requiresGuardianApprovalForActor(name, input, executionTarget)
+    ) {
+      const inputDigest = computeToolApprovalDigest(name, input);
+      needsGrantConsumption = true;
+      deferredConsumeParams = {
+        requestId: context.requestId,
+        toolName: name,
+        inputDigest,
+        consumingRequestId: context.requestId ?? `preexec-${context.sessionId}-${Date.now()}`,
+        assistantId: context.assistantId ?? 'self',
+        executionChannel: context.executionChannel,
+        conversationId: context.conversationId,
+        callSessionId: context.callSessionId,
+        requesterExternalUserId: context.requesterExternalUserId,
+      };
+    }
+
     // Gate tools not active for the current turn
     if (context.allowedToolNames && !context.allowedToolNames.has(name)) {
       const msg = `Tool "${name}" is not currently active. Load the skill that provides this tool first.`;
@@ -187,6 +242,89 @@ export class ToolApprovalHandler {
       return { allowed: false, result: { content: msg, isError: true } };
     }
 
+    // All policy gates passed. Now consume the scoped grant if one is
+    // required. Deferring consumption to this point ensures a downstream
+    // rejection (allowedToolNames, task-run preflight, registry lookup)
+    // does not waste the one-time-use grant.
+    //
+    // Retry polling is scoped to the voice channel where a race condition
+    // exists between fire-and-forget turn execution and LLM fallback grant
+    // minting (2-5s). Non-voice channels get an instant sync lookup so
+    // normal denials are not delayed.
+    if (needsGrantConsumption && deferredConsumeParams) {
+      const isVoice = context.executionChannel === 'voice';
+      const grantResult = await consumeGrantForInvocation(
+        deferredConsumeParams,
+        isVoice ? { signal: context.signal } : { maxWaitMs: 0 },
+      );
+
+      if (grantResult.ok) {
+        log.info({
+          toolName: name,
+          sessionId: context.sessionId,
+          conversationId: context.conversationId,
+          actorRole: context.guardianActorRole,
+          executionTarget,
+          grantId: grantResult.grant.id,
+        }, 'Scoped grant consumed — allowing untrusted actor tool invocation');
+
+        return { allowed: true, tool, grantConsumed: true };
+      }
+
+      // Treat abort as a cancellation — not a grant denial. This matches
+      // the abort check at the top of checkPreExecutionGates so the caller
+      // sees a consistent "Cancelled" result instead of a spurious
+      // guardian_approval_required denial during voice barge-in.
+      if (grantResult.reason === 'aborted') {
+        const durationMs = Date.now() - startTime;
+        emitLifecycleEvent({
+          type: 'error',
+          toolName: name,
+          executionTarget,
+          input,
+          workingDir: context.workingDir,
+          sessionId: context.sessionId,
+          conversationId: context.conversationId,
+          requestId: context.requestId,
+          riskLevel,
+          decision: 'error',
+          durationMs,
+          errorMessage: 'Cancelled',
+          isExpected: true,
+          errorCategory: 'tool_failure',
+        });
+        return { allowed: false, result: { content: 'Cancelled', isError: true } };
+      }
+
+      // No matching grant or race condition — deny.
+      const reason = guardianApprovalDeniedMessage(context.guardianActorRole, name);
+      log.warn({
+        toolName: name,
+        sessionId: context.sessionId,
+        conversationId: context.conversationId,
+        actorRole: context.guardianActorRole,
+        executionTarget,
+        reason: 'guardian_approval_required',
+        grantMissReason: grantResult.reason,
+      }, 'Guardian approval gate blocked untrusted actor tool invocation (no matching grant)');
+      const durationMs = Date.now() - startTime;
+      emitLifecycleEvent({
+        type: 'permission_denied',
+        toolName: name,
+        executionTarget,
+        input,
+        workingDir: context.workingDir,
+        sessionId: context.sessionId,
+        conversationId: context.conversationId,
+        requestId: context.requestId,
+        riskLevel,
+        decision: 'deny',
+        reason,
+        durationMs,
+      });
+      return { allowed: false, result: { content: reason, isError: true } };
+    }
+
     return { allowed: true, tool };
   }
 }

package/src/tools/tool-manifest.ts

@@ -12,6 +12,9 @@ import { credentialStoreTool } from './credentials/vault.js';
 import { memorySaveTool, memorySearchTool, memoryUpdateTool } from './memory/register.js';
 import type { LazyToolDescriptor } from './registry.js';
 import { vellumSkillsCatalogTool } from './skills/vellum-catalog.js';
+import { setAvatarTool } from './system/avatar-generator.js';
+import { navigateSettingsTabTool } from './system/navigate-settings.js';
+import { openSystemSettingsTool } from './system/open-system-settings.js';
 import { voiceConfigUpdateTool } from './system/voice-config.js';
 import type { Tool } from './types.js';
 import { screenWatchTool } from './watch/screen-watch.js';
@@ -68,6 +71,9 @@ export const explicitTools: Tool[] = [
   screenWatchTool,
   vellumSkillsCatalogTool,
   voiceConfigUpdateTool,
+  setAvatarTool,
+  openSystemSettingsTool,
+  navigateSettingsTabTool,
 ];
 
 // ── Lazy tool descriptors ───────────────────────────────────────────

package/src/tools/types.ts

@@ -138,6 +138,12 @@ export interface ToolContext {
   principal?: string;
   /** Guardian actor role for the session — used by the guardian control-plane policy gate. */
   guardianActorRole?: 'guardian' | 'non-guardian' | 'unverified_channel';
+  /** Channel through which the tool invocation originates (e.g. 'telegram', 'voice'). Used for scoped grant consumption. */
+  executionChannel?: string;
+  /** Voice/call session ID, if the invocation originates from a call. Used for scoped grant consumption. */
+  callSessionId?: string;
+  /** External user ID of the requester (non-guardian actor). Used for scoped grant consumption. */
+  requesterExternalUserId?: string;
 }
 
 export interface DiffInfo {

package/src/util/diff.ts

@@ -54,7 +54,7 @@ interface Hunk {
 }
 
 const CONTEXT_LINES = 3;
-const MAX_DIFF_LINES = 1000;
+const DEFAULT_MAX_EXACT_DIFF_LINES = 1000;
 
 /**
  * Group diff entries into hunks with surrounding context lines.
@@ -108,24 +108,44 @@ const CYAN = '\x1b[36m';
 const DIM = '\x1b[2m';
 const RESET = '\x1b[0m';
 
+export interface FormatDiffOptions {
+  maxExactLines?: number;
+}
+
+function formatLargeDiffFallback(oldLines: string[], newLines: string[], filePath: string): string {
+  let output = `${DIM}--- a/${filePath}${RESET}\n`;
+  output += `${DIM}+++ b/${filePath}${RESET}\n`;
+  output += `${CYAN}@@ -1,${oldLines.length} +1,${newLines.length} @@${RESET}\n`;
+
+  for (const line of oldLines) {
+    output += `${RED}-${line}${RESET}\n`;
+  }
+  for (const line of newLines) {
+    output += `${GREEN}+${line}${RESET}\n`;
+  }
+
+  return output;
+}
+
 /**
  * Format a colored unified diff from old and new file content.
  * Returns an empty string if the contents are identical.
  */
-export function formatDiff(oldContent: string, newContent: string, filePath: string): string {
+export function formatDiff(
+  oldContent: string,
+  newContent: string,
+  filePath: string,
+  options: FormatDiffOptions = {},
+): string {
   if (oldContent === newContent) return '';
 
   const oldLines = oldContent.split('\n');
   const newLines = newContent.split('\n');
+  const maxExactLines = options.maxExactLines ?? DEFAULT_MAX_EXACT_DIFF_LINES;
 
   // Guard against quadratic blowup on large files
-  if (oldLines.length > MAX_DIFF_LINES || newLines.length > MAX_DIFF_LINES) {
-    const removed = oldLines.length;
-    const added = newLines.length;
-    let output = `${DIM}--- a/${filePath}${RESET}\n`;
-    output += `${DIM}+++ b/${filePath}${RESET}\n`;
-    output += `${DIM}[Diff too large to display: ${removed} lines → ${added} lines]${RESET}\n`;
-    return output;
+  if (oldLines.length > maxExactLines || newLines.length > maxExactLines) {
+    return formatLargeDiffFallback(oldLines, newLines, filePath);
   }
 
   const entries = computeLineDiff(oldLines, newLines);
@@ -159,11 +179,14 @@ export function formatDiff(oldContent: string, newContent: string, filePath: str
 /**
  * Format a "new file" diff (everything is added).
  * Truncates to maxLines to avoid flooding the terminal.
+ * Pass `null` for unbounded output.
  */
-export function formatNewFileDiff(content: string, filePath: string, maxLines = 20): string {
+export function formatNewFileDiff(content: string, filePath: string, maxLines: number | null = 20): string {
   const lines = content.split('\n');
-  const truncated = lines.length > maxLines;
-  const displayLines = truncated ? lines.slice(0, maxLines) : lines;
+  const shouldTruncate = typeof maxLines === 'number' && Number.isFinite(maxLines);
+  const boundedMaxLines = shouldTruncate ? Math.max(0, Math.floor(maxLines)) : lines.length;
+  const truncated = lines.length > boundedMaxLines;
+  const displayLines = truncated ? lines.slice(0, boundedMaxLines) : lines;
 
   let output = `${DIM}--- /dev/null${RESET}\n`;
   output += `${DIM}+++ b/${filePath}${RESET}\n`;
@@ -174,7 +197,7 @@ export function formatNewFileDiff(content: string, filePath: string, maxLines =
   }
 
   if (truncated) {
-    output += `${DIM}... ${lines.length - maxLines} more lines${RESET}\n`;
+    output += `${DIM}... ${lines.length - boundedMaxLines} more lines${RESET}\n`;
   }
 
   return output;

package/Dockerfile.sandbox

@@ -1,5 +0,0 @@
-FROM node:20-slim
-
-RUN apt-get update \
- && apt-get install -y --no-install-recommends curl ca-certificates bash jq python3 \
- && rm -rf /var/lib/apt/lists/*