@vellumai/assistant 0.3.21 → 0.3.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "type": "module",
   "bin": {
     "vellum": "./src/index.ts"

package/src/__tests__/host-shell-tool.test.ts

@@ -424,6 +424,31 @@ describe('host_bash — environment setup', () => {
     expect(result.content).toContain('HOME=');
     expect(result.content.trim()).not.toBe('HOME=');
   });
+
+  test('injects INTERNAL_GATEWAY_BASE_URL and GATEWAY_BASE_URL for host_bash commands', async () => {
+    const originalGatewayBase = process.env.GATEWAY_INTERNAL_BASE_URL;
+    const originalIngressBase = process.env.INGRESS_PUBLIC_BASE_URL;
+    process.env.GATEWAY_INTERNAL_BASE_URL = 'http://gateway.internal:9000/';
+    process.env.INGRESS_PUBLIC_BASE_URL = 'https://gw.example.com/';
+    try {
+      const result = await hostShellTool.execute({
+        command: 'echo "$INTERNAL_GATEWAY_BASE_URL|$GATEWAY_BASE_URL"',
+      }, makeContext());
+      expect(result.isError).toBe(false);
+      expect(result.content.trim()).toBe('http://gateway.internal:9000|https://gw.example.com');
+    } finally {
+      if (originalGatewayBase === undefined) {
+        delete process.env.GATEWAY_INTERNAL_BASE_URL;
+      } else {
+        process.env.GATEWAY_INTERNAL_BASE_URL = originalGatewayBase;
+      }
+      if (originalIngressBase === undefined) {
+        delete process.env.INGRESS_PUBLIC_BASE_URL;
+      } else {
+        process.env.INGRESS_PUBLIC_BASE_URL = originalIngressBase;
+      }
+    }
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/__tests__/mcp-cli.test.ts

@@ -0,0 +1,258 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+
+const CLI = join(import.meta.dir, '..', 'index.ts');
+
+let testDataDir: string;
+let configPath: string;
+
+function runMcp(subcommand: string, args: string[] = []): { stdout: string; stderr: string; exitCode: number } {
+  const result = spawnSync('bun', ['run', CLI, 'mcp', subcommand, ...args], {
+    encoding: 'utf-8',
+    timeout: 10_000,
+    env: { ...process.env, BASE_DATA_DIR: testDataDir },
+  });
+  return {
+    stdout: (result.stdout ?? '').toString(),
+    stderr: (result.stderr ?? '').toString(),
+    exitCode: result.status ?? 1,
+  };
+}
+
+function runMcpList(args: string[] = []) {
+  return runMcp('list', args);
+}
+
+function runMcpAdd(name: string, args: string[]) {
+  return runMcp('add', [name, ...args]);
+}
+
+function writeConfig(config: Record<string, unknown>): void {
+  writeFileSync(configPath, JSON.stringify(config), 'utf-8');
+}
+
+function readConfig(): Record<string, unknown> {
+  return JSON.parse(readFileSync(configPath, 'utf-8'));
+}
+
+describe('vellum mcp list', () => {
+  beforeAll(() => {
+    testDataDir = join(tmpdir(), `vellum-mcp-cli-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    const workspaceDir = join(testDataDir, '.vellum', 'workspace');
+    mkdirSync(workspaceDir, { recursive: true });
+    configPath = join(workspaceDir, 'config.json');
+    writeConfig({});
+  });
+
+  afterAll(() => {
+    rmSync(testDataDir, { recursive: true, force: true });
+  });
+
+  beforeEach(() => {
+    writeConfig({});
+  });
+
+  test('shows message when no MCP servers configured', () => {
+    const { stdout, exitCode } = runMcpList();
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('No MCP servers configured');
+  });
+
+  test('lists configured servers', () => {
+    writeConfig({
+      mcp: {
+        servers: {
+          'test-server': {
+            transport: { type: 'streamable-http', url: 'https://example.com/mcp' },
+            enabled: true,
+            defaultRiskLevel: 'medium',
+          },
+        },
+      },
+    });
+
+    const { stdout, exitCode } = runMcpList();
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('1 MCP server(s) configured');
+    expect(stdout).toContain('test-server');
+    expect(stdout).toContain('streamable-http');
+    expect(stdout).toContain('https://example.com/mcp');
+    expect(stdout).toContain('medium');
+  });
+
+  test('shows disabled status', () => {
+    writeConfig({
+      mcp: {
+        servers: {
+          'disabled-server': {
+            transport: { type: 'sse', url: 'https://example.com/sse' },
+            enabled: false,
+            defaultRiskLevel: 'high',
+          },
+        },
+      },
+    });
+
+    const { stdout, exitCode } = runMcpList();
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('disabled');
+  });
+
+  test('shows stdio command info', () => {
+    writeConfig({
+      mcp: {
+        servers: {
+          'stdio-server': {
+            transport: { type: 'stdio', command: 'npx', args: ['-y', 'some-mcp-server'] },
+            enabled: true,
+            defaultRiskLevel: 'low',
+          },
+        },
+      },
+    });
+
+    const { stdout, exitCode } = runMcpList();
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('stdio-server');
+    expect(stdout).toContain('stdio');
+    expect(stdout).toContain('npx -y some-mcp-server');
+    expect(stdout).toContain('low');
+  });
+
+  test('--json outputs valid JSON', () => {
+    writeConfig({
+      mcp: {
+        servers: {
+          'json-server': {
+            transport: { type: 'streamable-http', url: 'https://example.com/mcp' },
+            enabled: true,
+            defaultRiskLevel: 'high',
+          },
+        },
+      },
+    });
+
+    const { stdout, exitCode } = runMcpList(['--json']);
+    expect(exitCode).toBe(0);
+    const parsed = JSON.parse(stdout);
+    expect(Array.isArray(parsed)).toBe(true);
+    expect(parsed).toHaveLength(1);
+    expect(parsed[0].id).toBe('json-server');
+    expect(parsed[0].transport.url).toBe('https://example.com/mcp');
+  });
+
+  test('--json outputs empty array when no servers', () => {
+    const { stdout, exitCode } = runMcpList(['--json']);
+    expect(exitCode).toBe(0);
+    const parsed = JSON.parse(stdout);
+    expect(parsed).toEqual([]);
+  });
+});
+
+describe('vellum mcp add', () => {
+  beforeAll(() => {
+    testDataDir = join(tmpdir(), `vellum-mcp-add-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    const workspaceDir = join(testDataDir, '.vellum', 'workspace');
+    mkdirSync(workspaceDir, { recursive: true });
+    configPath = join(workspaceDir, 'config.json');
+    writeConfig({});
+  });
+
+  afterAll(() => {
+    rmSync(testDataDir, { recursive: true, force: true });
+  });
+
+  beforeEach(() => {
+    writeConfig({});
+  });
+
+  test('adds a streamable-http server', () => {
+    const { stdout, exitCode } = runMcpAdd('test-http', [
+      '-t', 'streamable-http', '-u', 'https://example.com/mcp', '-r', 'medium',
+    ]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('Added MCP server "test-http"');
+
+    const updated = readConfig();
+    const servers = (updated.mcp as Record<string, unknown> | undefined)?.servers as Record<string, unknown> | undefined;
+    const server = servers?.['test-http'] as Record<string, unknown>;
+    expect(server).toBeDefined();
+    expect((server.transport as Record<string, unknown>).type).toBe('streamable-http');
+    expect((server.transport as Record<string, unknown>).url).toBe('https://example.com/mcp');
+    expect(server.defaultRiskLevel).toBe('medium');
+    expect(server.enabled).toBe(true);
+  });
+
+  test('adds a stdio server with args', () => {
+    const { stdout, exitCode } = runMcpAdd('test-stdio', [
+      '-t', 'stdio', '-c', 'npx', '-a', '-y', 'some-server', '-r', 'low',
+    ]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('Added MCP server "test-stdio"');
+
+    const updated = readConfig();
+    const servers = (updated.mcp as Record<string, unknown> | undefined)?.servers as Record<string, unknown> | undefined;
+    const server = servers?.['test-stdio'] as Record<string, unknown>;
+    const transport = server.transport as Record<string, unknown>;
+    expect(transport.type).toBe('stdio');
+    expect(transport.command).toBe('npx');
+    expect(transport.args).toEqual(['-y', 'some-server']);
+  });
+
+  test('adds server as disabled with --disabled flag', () => {
+    const { exitCode } = runMcpAdd('test-disabled', [
+      '-t', 'sse', '-u', 'https://example.com/sse', '--disabled',
+    ]);
+    expect(exitCode).toBe(0);
+
+    const updated = readConfig();
+    const servers = (updated.mcp as Record<string, unknown> | undefined)?.servers as Record<string, unknown> | undefined;
+    const server = servers?.['test-disabled'] as Record<string, unknown>;
+    expect(server.enabled).toBe(false);
+  });
+
+  test('rejects duplicate server name', () => {
+    writeConfig({
+      mcp: {
+        servers: {
+          existing: {
+            transport: { type: 'sse', url: 'https://example.com' },
+            enabled: true,
+            defaultRiskLevel: 'high',
+          },
+        },
+      },
+    });
+
+    const { stderr } = runMcpAdd('existing', [
+      '-t', 'sse', '-u', 'https://other.com',
+    ]);
+    expect(stderr).toContain('already exists');
+  });
+
+  test('rejects stdio without --command', () => {
+    const { stderr } = runMcpAdd('bad-stdio', ['-t', 'stdio']);
+    expect(stderr).toContain('--command is required');
+  });
+
+  test('rejects streamable-http without --url', () => {
+    const { stderr } = runMcpAdd('bad-http', ['-t', 'streamable-http']);
+    expect(stderr).toContain('--url is required');
+  });
+
+  test('defaults risk to high', () => {
+    const { exitCode } = runMcpAdd('default-risk', [
+      '-t', 'sse', '-u', 'https://example.com/sse',
+    ]);
+    expect(exitCode).toBe(0);
+
+    const updated = readConfig();
+    const servers = (updated.mcp as Record<string, unknown> | undefined)?.servers as Record<string, unknown> | undefined;
+    const server = servers?.['default-risk'] as Record<string, unknown>;
+    expect(server.defaultRiskLevel).toBe('high');
+  });
+});

package/src/__tests__/terminal-tools.test.ts

@@ -446,6 +446,23 @@ describe('buildSanitizedEnv', () => {
     expect(env.LC_CTYPE).toBe('UTF-8');
   });
 
+  test('injects INTERNAL_GATEWAY_BASE_URL from gateway config', () => {
+    process.env.GATEWAY_INTERNAL_BASE_URL = 'http://gateway.internal:9000/';
+    const env = buildSanitizedEnv();
+    expect(env.INTERNAL_GATEWAY_BASE_URL).toBe('http://gateway.internal:9000');
+    delete process.env.GATEWAY_INTERNAL_BASE_URL;
+  });
+
+  test('injects GATEWAY_BASE_URL from public ingress when configured', () => {
+    process.env.GATEWAY_INTERNAL_BASE_URL = 'http://gateway.internal:9000/';
+    process.env.INGRESS_PUBLIC_BASE_URL = 'https://gw.example.com/';
+    const env = buildSanitizedEnv();
+    expect(env.INTERNAL_GATEWAY_BASE_URL).toBe('http://gateway.internal:9000');
+    expect(env.GATEWAY_BASE_URL).toBe('https://gw.example.com');
+    delete process.env.GATEWAY_INTERNAL_BASE_URL;
+    delete process.env.INGRESS_PUBLIC_BASE_URL;
+  });
+
   test('result is a plain object with no prototype-inherited secrets', () => {
     const env = buildSanitizedEnv();
     const keys = Object.keys(env);
@@ -453,6 +470,8 @@ describe('buildSanitizedEnv', () => {
       'PATH', 'HOME', 'TERM', 'LANG', 'EDITOR', 'SHELL', 'USER', 'TMPDIR',
       'LC_ALL', 'LC_CTYPE', 'XDG_RUNTIME_DIR', 'DISPLAY', 'COLORTERM',
       'TERM_PROGRAM', 'SSH_AUTH_SOCK', 'SSH_AGENT_PID', 'GPG_TTY', 'GNUPGHOME',
+      'INTERNAL_GATEWAY_BASE_URL',
+      'GATEWAY_BASE_URL',
     ];
     for (const key of keys) {
       expect(safeKeys).toContain(key);
@@ -684,4 +703,3 @@ describe('formatShellOutput', () => {
     expect(result.content.length).toBeLessThan(60_000);
   });
 });
-

package/src/__tests__/tool-executor.test.ts

@@ -1844,7 +1844,7 @@ describe('buildSanitizedEnv — baseline: credential exclusion', () => {
       'PATH', 'HOME', 'TERM', 'LANG', 'EDITOR', 'SHELL', 'USER',
       'TMPDIR', 'LC_ALL', 'LC_CTYPE', 'XDG_RUNTIME_DIR', 'DISPLAY',
       'COLORTERM', 'TERM_PROGRAM', 'SSH_AUTH_SOCK', 'SSH_AGENT_PID',
-      'GPG_TTY', 'GNUPGHOME',
+      'GPG_TTY', 'GNUPGHOME', 'INTERNAL_GATEWAY_BASE_URL', 'GATEWAY_BASE_URL',
     ];
 
     const env = buildSanitizedEnv();

package/src/cli/mcp.ts

@@ -1,6 +1,6 @@
 import type { Command } from 'commander';
 
-import { loadRawConfig } from '../config/loader.js';
+import { loadRawConfig, saveRawConfig } from '../config/loader.js';
 import type { McpConfig, McpServerConfig } from '../config/mcp-schema.js';
 import { getCliLogger } from '../util/logger.js';
 
@@ -29,13 +29,19 @@ export function registerMcpCommand(program: Command): void {
       }
 
       if (opts.json) {
-        const result = entries.map(([id, config]) => ({ id, ...config }));
+        const result = entries
+          .filter(([, config]) => config && typeof config === 'object')
+          .map(([id, config]) => ({ id, ...config }));
         process.stdout.write(JSON.stringify(result, null, 2) + '\n');
         return;
       }
 
       log.info(`${entries.length} MCP server(s) configured:\n`);
       for (const [id, cfg] of entries) {
+        if (!cfg || typeof cfg !== 'object') {
+          log.info(`  ${id} (invalid config — skipped)\n`);
+          continue;
+        }
         const enabled = cfg.enabled !== false;
         const transport = cfg.transport;
         const risk = cfg.defaultRiskLevel ?? 'high';
@@ -55,4 +61,75 @@ export function registerMcpCommand(program: Command): void {
         log.info('');
       }
     });
+
+  mcp
+    .command('add <name>')
+    .description('Add an MCP server configuration')
+    .requiredOption('-t, --transport-type <type>', 'Transport type: stdio, sse, or streamable-http')
+    .option('-u, --url <url>', 'Server URL (for sse/streamable-http)')
+    .option('-c, --command <cmd>', 'Command to run (for stdio)')
+    .option('-a, --args <args...>', 'Command arguments (for stdio)')
+    .option('-r, --risk <level>', 'Default risk level: low, medium, or high', 'high')
+    .option('--disabled', 'Add as disabled')
+    .action((name: string, opts: {
+      transportType: string;
+      url?: string;
+      command?: string;
+      args?: string[];
+      risk: string;
+      disabled?: boolean;
+    }) => {
+      const raw = loadRawConfig();
+      if (!raw.mcp) raw.mcp = { servers: {} };
+      const mcpConfig = raw.mcp as Record<string, unknown>;
+      if (!mcpConfig.servers) mcpConfig.servers = {};
+      const servers = mcpConfig.servers as Record<string, unknown>;
+
+      if (servers[name]) {
+        log.error(`MCP server "${name}" already exists. Remove it first with: vellum mcp remove ${name}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      let transport: Record<string, unknown>;
+      switch (opts.transportType) {
+        case 'stdio':
+          if (!opts.command) {
+            log.error('--command is required for stdio transport');
+            process.exitCode = 1;
+            return;
+          }
+          transport = { type: 'stdio', command: opts.command, args: opts.args ?? [] };
+          break;
+        case 'sse':
+        case 'streamable-http':
+          if (!opts.url) {
+            log.error(`--url is required for ${opts.transportType} transport`);
+            process.exitCode = 1;
+            return;
+          }
+          transport = { type: opts.transportType, url: opts.url };
+          break;
+        default:
+          log.error(`Unknown transport type: ${opts.transportType}. Must be stdio, sse, or streamable-http`);
+          process.exitCode = 1;
+          return;
+      }
+
+      if (!['low', 'medium', 'high'].includes(opts.risk)) {
+        log.error(`Invalid risk level: ${opts.risk}. Must be low, medium, or high`);
+        process.exitCode = 1;
+        return;
+      }
+
+      servers[name] = {
+        transport,
+        enabled: !opts.disabled,
+        defaultRiskLevel: opts.risk,
+      };
+
+      saveRawConfig(raw);
+      log.info(`Added MCP server "${name}" (${opts.transportType})`);
+      log.info('Restart the daemon for changes to take effect: vellum daemon restart');
+    });
 }

package/src/config/bundled-skills/phone-calls/SKILL.md

@@ -621,7 +621,7 @@ Run the **public-ingress** skill to set up ngrok and configure `ingress.publicBa
 
 ### Call connects but no audio / one-way audio
 - The ConversationRelay WebSocket may not be connecting. Check that `ingress.publicBaseUrl` is correct and the tunnel is active
-- Verify the gateway is running on `http://127.0.0.1:${GATEWAY_PORT:-7830}`
+- Verify the gateway is running at `$GATEWAY_BASE_URL`
 
 ### "Number not eligible for caller identity"
 The user's phone number is not owned by or verified with the Twilio account. The number must be either purchased through Twilio or added as a verified caller ID at https://console.twilio.com/us1/develop/phone-numbers/manage/verified.

package/src/config/bundled-skills/public-ingress/SKILL.md

@@ -24,7 +24,7 @@ First, check whether ingress is already configured:
 vellum config get ingress.publicBaseUrl
 ```
 
-Also determine the local gateway target. The gateway listens on `http://127.0.0.1:${GATEWAY_PORT:-7830}` by default.
+Use the injected `INTERNAL_GATEWAY_BASE_URL` as the local gateway target before proceeding.
 
 If `ingress.publicBaseUrl` is already set and the tunnel is running (check via `curl -s http://127.0.0.1:4040/api/tunnels`), tell the user the current status and ask if they want to reconfigure or if this is sufficient.
 
@@ -109,10 +109,10 @@ pkill -f ngrok || true
 sleep 1
 ```
 
-Start ngrok in the background, tunneling to the local gateway:
+Start ngrok in the background, tunneling to the local gateway target:
 
 ```bash
-nohup ngrok http http://127.0.0.1:${GATEWAY_PORT:-7830} --log=stdout > /tmp/ngrok.log 2>&1 &
+nohup ngrok http "$INTERNAL_GATEWAY_BASE_URL" --log=stdout > /tmp/ngrok.log 2>&1 &
 echo $! > /tmp/ngrok.pid
 ```
 
@@ -169,14 +169,14 @@ vellum config get ingress.enabled
 Summarize the setup:
 
 - **Public URL:** `<the-url>` (this is your `ingress.publicBaseUrl`)
-- **Local gateway:** `http://127.0.0.1:${GATEWAY_PORT:-7830}`
+- **Local gateway target:** `$INTERNAL_GATEWAY_BASE_URL`
 - **ngrok dashboard:** http://127.0.0.1:4040
 
 Provide useful follow-up commands:
 
 - **Check tunnel status:** `curl -s http://127.0.0.1:4040/api/tunnels | python3 -c "import sys,json; [print(t['public_url']) for t in json.load(sys.stdin)['tunnels']]"`
 - **View ngrok logs:** `cat /tmp/ngrok.log`
-- **Restart tunnel:** `pkill -f ngrok; sleep 1; nohup ngrok http http://127.0.0.1:${GATEWAY_PORT:-7830} --log=stdout > /tmp/ngrok.log 2>&1 &`
+- **Restart tunnel:** `pkill -f ngrok; sleep 1; nohup ngrok http "$INTERNAL_GATEWAY_BASE_URL" --log=stdout > /tmp/ngrok.log 2>&1 &`
 - **Stop tunnel:** `pkill -f ngrok`
 - **Rotate URL:** Stop and restart ngrok (free tier assigns a new URL each time; update `ingress.publicBaseUrl` afterward)
 
@@ -194,7 +194,7 @@ Sign in to https://dashboard.ngrok.com, copy a fresh token from the "Your Authto
 The ngrok process may not be running. Check with `ps aux | grep ngrok`. If not running, start it per Step 4. If running but 4040 is unresponsive, check `/tmp/ngrok.log` for errors.
 
 ### Gateway not reachable on local target
-Ensure the Vellum gateway is running on `http://127.0.0.1:${GATEWAY_PORT:-7830}`. Check with `curl -s http://127.0.0.1:${GATEWAY_PORT:-7830}/health`. If not running, start the assistant daemon first.
+Ensure the Vellum gateway is running on `$INTERNAL_GATEWAY_BASE_URL`. Check with `curl -s "$INTERNAL_GATEWAY_BASE_URL/healthz"`. If not running, start the assistant daemon first.
 
 ### "Too many connections" or tunnel limit errors
 ngrok's free tier allows one tunnel at a time. Stop any other ngrok tunnels before starting a new one.

package/src/config/feature-flag-registry.json

@@ -41,6 +41,14 @@
       "description": "Enable X (Twitter) skill section in the system prompt",
       "defaultEnabled": true
     },
+    {
+      "id": "collect-usage-data",
+      "scope": "assistant",
+      "key": "feature_flags.collect-usage-data.enabled",
+      "label": "Collect usage data",
+      "description": "Send crash reports and error diagnostics to help improve the app",
+      "defaultEnabled": true
+    },
     {
       "id": "user-hosted-enabled",
       "scope": "macos",

package/src/config/schema.ts

@@ -68,6 +68,16 @@ export {
   TimeoutConfigSchema,
   UiConfigSchema,
 } from './core-schema.js';
+export type {
+  McpConfig,
+  McpServerConfig,
+  McpTransport,
+} from './mcp-schema.js';
+export {
+  McpConfigSchema,
+  McpServerConfigSchema,
+  McpTransportSchema,
+} from './mcp-schema.js';
 export type {
   MemoryCleanupConfig,
   MemoryConfig,
@@ -114,16 +124,6 @@ export type {
 export {
   SandboxConfigSchema,
 } from './sandbox-schema.js';
-export type {
-  McpConfig,
-  McpServerConfig,
-  McpTransport,
-} from './mcp-schema.js';
-export {
-  McpConfigSchema,
-  McpServerConfigSchema,
-  McpTransportSchema,
-} from './mcp-schema.js';
 export type {
   RemotePolicyConfig,
   RemoteProviderConfig,

package/src/config/vellum-skills/guardian-verify-setup/SKILL.md

@@ -9,10 +9,10 @@ You are helping your user set up guardian verification for a messaging channel (
 
 ## Prerequisites
 
-- The gateway API is available at `http://localhost:7830` (or the configured gateway port).
+- Use the injected `INTERNAL_GATEWAY_BASE_URL` for gateway API calls.
 - Never call the daemon runtime port directly; always call the gateway URL.
 - The bearer token is stored at `~/.vellum/http-token`. Read it with: `TOKEN=$(cat ~/.vellum/http-token)`.
-- Run shell commands for this skill with `host_bash` (not sandbox `bash`) so host auth/token and localhost routing are reliable.
+- Run shell commands for this skill with `host_bash` (not sandbox `bash`) so host auth/token and gateway routing are reliable.
 - Keep narration minimal: execute required calls first, then provide a concise status update. Do not narrate internal install/check/load chatter unless something fails.
 
 ## Step 1: Confirm Channel
@@ -40,7 +40,7 @@ Execute the outbound start request:
 
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
-curl -s -X POST http://localhost:7830/v1/integrations/guardian/outbound/start \
+curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/guardian/outbound/start" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $TOKEN" \
   -d '{"channel": "<channel>", "destination": "<destination>"}'
@@ -78,7 +78,7 @@ If the user says they did not receive the code or asks to resend:
 
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
-curl -s -X POST http://localhost:7830/v1/integrations/guardian/outbound/resend \
+curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/guardian/outbound/resend" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $TOKEN" \
   -d '{"channel": "<channel>"}'
@@ -108,7 +108,7 @@ If the user wants to cancel the verification:
 
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
-curl -s -X POST http://localhost:7830/v1/integrations/guardian/outbound/cancel \
+curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/guardian/outbound/cancel" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $TOKEN" \
   -d '{"channel": "<channel>"}'
@@ -127,7 +127,7 @@ For **voice** verification only: after telling the user their code and instructi
 
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
-curl -s http://localhost:7830/v1/integrations/guardian/status?channel=voice \
+curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/guardian/status?channel=voice" \
   -H "Authorization: Bearer $TOKEN"
 ```
 
@@ -154,7 +154,7 @@ After the user reports entering the code, verify the binding was created:
 
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
-curl -s http://localhost:7830/v1/integrations/guardian/status?channel=<channel> \
+curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/guardian/status?channel=<channel>" \
   -H "Authorization: Bearer $TOKEN"
 ```
 

package/src/config/vellum-skills/telegram-setup/SKILL.md

@@ -12,7 +12,7 @@ You are helping your user connect a Telegram bot to the Vellum Assistant gateway
 
 Before beginning setup, verify these conditions are met:
 
-1. **Gateway API base URL is set and reachable:** Use the configured gateway URL in `GATEWAY_BASE_URL` (from Settings "Local Gateway Target"), then run `curl -sf "$GATEWAY_BASE_URL/healthz"` — it should return gateway health JSON (for example `{"status":"ok"}`). If it fails, tell the user to start the daemon with `vellum daemon start` and wait for it to become healthy before continuing.
+1. **Gateway API base URL is set and reachable:** Use the injected `INTERNAL_GATEWAY_BASE_URL`, then run `curl -sf "$INTERNAL_GATEWAY_BASE_URL/healthz"` — it should return gateway health JSON (for example `{"status":"ok"}`). If it fails, tell the user to start the daemon with `vellum daemon start` and wait for it to become healthy before continuing.
 2. **Public ingress URL is configured.** The gateway webhook URL is derived from `${ingress.publicBaseUrl}/webhooks/telegram`. If the ingress URL is not configured, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the URL before continuing.
 3. **Use gateway control-plane routes only.** Telegram setup/config actions in this skill must call gateway endpoints under `/v1/integrations/telegram/*` — never call the daemon runtime port directly.
 
@@ -37,7 +37,7 @@ The token is collected securely via a system-level prompt and is never exposed i
 After the token is collected, call the composite setup endpoint which validates the token, stores credentials, and registers bot commands in a single request:
 
 ```bash
-curl -sf -X POST "$GATEWAY_BASE_URL/v1/integrations/telegram/setup" \
+curl -sf -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/telegram/setup" \
   -H "Authorization: Bearer $(cat ~/.vellum/http-token)" \
   -H "Content-Type: application/json" \
   -d '{}'
@@ -98,7 +98,7 @@ If routing is misconfigured, inbound Telegram messages will be rejected and the
 Before reporting success, confirm the guardian binding was actually created. Check the guardian binding status:
 
 ```bash
-curl -sf "$GATEWAY_BASE_URL/v1/integrations/guardian/status?channel=telegram" \
+curl -sf "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/guardian/status?channel=telegram" \
   -H "Authorization: Bearer $(cat ~/.vellum/http-token)"
 ```
 
@@ -117,7 +117,7 @@ Summarize what was done:
 - Guardian identity: {verified | not configured}
 - Guardian verification status: {verified via outbound flow | skipped}
 - Routing configuration validated
-- To re-check guardian status later, use: `curl -sf "$GATEWAY_BASE_URL/v1/integrations/guardian/status?channel=telegram" -H "Authorization: Bearer $(cat ~/.vellum/http-token)"`
+- To re-check guardian status later, use: `curl -sf "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/guardian/status?channel=telegram" -H "Authorization: Bearer $(cat ~/.vellum/http-token)"`
 
 The gateway automatically detects credentials from the vault, reconciles the Telegram webhook registration, and begins accepting Telegram webhooks shortly. In single-assistant mode, routing is automatically configured — no manual environment variable configuration or webhook registration is needed. If the webhook secret changes later, the gateway's credential watcher will automatically re-register the webhook. If the ingress URL changes (e.g., tunnel restart), the assistant daemon triggers an immediate internal reconcile so the webhook re-registers automatically without a gateway restart.
 

package/src/config/vellum-skills/trusted-contacts/SKILL.md

@@ -9,7 +9,7 @@ You are helping your user manage trusted contacts and invite links for the Vellu
 
 ## Prerequisites
 
-- The gateway API is available at `http://localhost:7830` (or the configured gateway port).
+- Use the injected `INTERNAL_GATEWAY_BASE_URL` for gateway API calls.
 - Use gateway control-plane routes only: this skill calls `/v1/ingress/*` and `/v1/integrations/telegram/config` on the gateway, never the daemon runtime port directly.
 - The bearer token is stored at `~/.vellum/http-token`. Read it with: `TOKEN=$(cat ~/.vellum/http-token)`.
 
@@ -29,7 +29,7 @@ Use this to show the user who currently has access, or to look up a specific con
 
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
-curl -s http://localhost:7830/v1/ingress/members \
+curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/members" \
   -H "Authorization: Bearer $TOKEN"
 ```
 
@@ -40,7 +40,7 @@ Optional query parameters for filtering:
 
 Example with filters:
 ```bash
-curl -s "http://localhost:7830/v1/ingress/members?sourceChannel=telegram&status=active" \
+curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/members?sourceChannel=telegram&status=active" \
   -H "Authorization: Bearer $TOKEN"
 ```
 
@@ -65,7 +65,7 @@ Ask the user: *"I'll add [name/identifier] on [channel] as an allowed contact. S
 
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
-curl -s -X POST http://localhost:7830/v1/ingress/members \
+curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/members" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $TOKEN" \
   -d '{
@@ -97,7 +97,7 @@ First, list members to find the member's `id`, then revoke:
 
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
-curl -s -X DELETE "http://localhost:7830/v1/ingress/members/<member_id>" \
+curl -s -X DELETE "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/members/<member_id>" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"reason": "<optional reason>"}'
@@ -113,7 +113,7 @@ Ask the user: *"I'll block [name/identifier]. They will be permanently denied fr
 
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
-curl -s -X POST "http://localhost:7830/v1/ingress/members/<member_id>/block" \
+curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/members/<member_id>/block" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $TOKEN" \
   -d '{"reason": "<optional reason>"}'
@@ -125,7 +125,7 @@ Use this when the guardian wants to invite someone to message the assistant on T
 
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
-curl -s -X POST http://localhost:7830/v1/ingress/invites \
+curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/invites" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $TOKEN" \
   -d '{
@@ -146,7 +146,7 @@ The response contains `{ ok: true, invite: { id, token, ... } }`. The `token` fi
 
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
-curl -s http://localhost:7830/v1/integrations/telegram/config \
+curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/telegram/config" \
   -H "Authorization: Bearer $TOKEN"
 ```
 
@@ -174,7 +174,7 @@ Use this to show the guardian their active (and optionally all) invite links.
 
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
-curl -s "http://localhost:7830/v1/ingress/invites?sourceChannel=telegram" \
+curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/invites?sourceChannel=telegram" \
   -H "Authorization: Bearer $TOKEN"
 ```
 
@@ -205,7 +205,7 @@ First, list invites to find the invite's `id`, then revoke:
 
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
-curl -s -X DELETE "http://localhost:7830/v1/ingress/invites/<invite_id>" \
+curl -s -X DELETE "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/invites/<invite_id>" \
   -H "Authorization: Bearer $TOKEN"
 ```
 

package/src/config/vellum-skills/twilio-setup/SKILL.md

@@ -228,10 +228,10 @@ To re-check guardian status later, query the channel(s) that were verified:
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
 # Check SMS guardian status
-curl -s http://localhost:7830/v1/integrations/guardian/status?channel=sms \
+curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/guardian/status?channel=sms" \
   -H "Authorization: Bearer $TOKEN"
 # Check voice guardian status
-curl -s http://localhost:7830/v1/integrations/guardian/status?channel=voice \
+curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/guardian/status?channel=voice" \
   -H "Authorization: Bearer $TOKEN"
 ```
 

package/src/daemon/lifecycle.ts

@@ -8,6 +8,7 @@ import { reconcileCallsOnStartup } from '../calls/call-recovery.js';
 import { setRelayBroadcast } from '../calls/relay-server.js';
 import { TwilioConversationRelayProvider } from '../calls/twilio-provider.js';
 import { setVoiceBridgeDeps } from '../calls/voice-session-bridge.js';
+import { isAssistantFeatureFlagEnabled } from '../config/assistant-feature-flags.js';
 import {
   getQdrantUrlEnv,
   getRuntimeHttpHost,
@@ -21,8 +22,9 @@ import { syncUpdateBulletinOnStartup } from '../config/update-bulletin.js';
 import { HeartbeatService } from '../heartbeat/heartbeat-service.js';
 import { getHookManager } from '../hooks/manager.js';
 import { installTemplates } from '../hooks/templates.js';
-import { initSentry } from '../instrument.js';
+import { closeSentry, initSentry } from '../instrument.js';
 import { initLogfire } from '../logfire.js';
+import { getMcpServerManager } from '../mcp/manager.js';
 import * as attachmentsStore from '../memory/attachments-store.js';
 import * as conversationStore from '../memory/conversation-store.js';
 import { initializeDb } from '../memory/db.js';
@@ -54,7 +56,6 @@ import { createGuardianActionCopyGenerator, createGuardianFollowUpConversationGe
 import { initPairingHandlers } from './handlers/pairing.js';
 import { installCliLaunchers } from './install-cli-launchers.js';
 import type { ServerMessage } from './ipc-protocol.js';
-import { getMcpServerManager } from '../mcp/manager.js';
 import { initializeProvidersAndTools, registerMessagingProviders,registerWatcherProviders } from './providers-setup.js';
 import { seedInterfaceFiles } from './seed-files.js';
 import { DaemonServer } from './server.js';
@@ -96,7 +97,11 @@ export async function runDaemon(): Promise<void> {
   let socketCreated = false;
 
   try {
+    // Initialize crash reporting eagerly so early startup failures are
+    // captured. After config loads we check the opt-out flag and call
+    // closeSentry() if the user has disabled it.
     initSentry();
+
     await initLogfire();
 
     // Migration order matters: first move legacy flat files into the data dir
@@ -173,6 +178,13 @@ export async function runDaemon(): Promise<void> {
       initLogger({ dir: config.logFile.dir, retentionDays: config.logFile.retentionDays });
     }
 
+    // If the user has opted out of crash reporting, stop Sentry from capturing
+    // future events. Early-startup crashes before this point are still captured.
+    const collectUsageData = isAssistantFeatureFlagEnabled('feature_flags.collect-usage-data.enabled', config);
+    if (!collectUsageData) {
+      await closeSentry();
+    }
+
     await initializeProvidersAndTools(config);
 
     // Start the IPC socket BEFORE Qdrant so that clients can connect

package/src/daemon/shutdown-handlers.ts

@@ -2,8 +2,8 @@ import * as Sentry from '@sentry/node';
 
 import type { HeartbeatService } from '../heartbeat/heartbeat-service.js';
 import type { HookManager } from '../hooks/manager.js';
-import { getSqlite, resetDb } from '../memory/db.js';
 import type { McpServerManager } from '../mcp/manager.js';
+import { getSqlite, resetDb } from '../memory/db.js';
 import type { QdrantManager } from '../memory/qdrant-manager.js';
 import type { RuntimeHttpServer } from '../runtime/http-server.js';
 import { browserManager } from '../tools/browser/browser-manager.js';

package/src/instrument.ts

@@ -32,7 +32,12 @@ function redactObject(obj: unknown): unknown {
   return obj;
 }
 
-/** Call after dotenv has loaded so SENTRY_DSN is available. */
+/**
+ * Call after dotenv has loaded so SENTRY_DSN is available.
+ * Always initializes Sentry to capture early startup crashes. If the user
+ * later opts out via the "collect-usage-data" feature flag, call closeSentry()
+ * after config is loaded to stop future event capturing.
+ */
 export function initSentry(): void {
   Sentry.init({
     dsn: getSentryDsn(),
@@ -60,3 +65,12 @@ export function initSentry(): void {
     },
   });
 }
+
+/**
+ * Stop capturing future Sentry events. Called after config loads when the
+ * user has opted out of crash reporting so that early-startup crashes are
+ * still captured but subsequent events are suppressed.
+ */
+export async function closeSentry(): Promise<void> {
+  await Sentry.close();
+}

package/src/mcp/client.ts

@@ -50,7 +50,7 @@ export class McpClient {
     } catch (err) {
       // Clean up the transport on failure (e.g., kill spawned stdio process)
       try { await this.client.close(); } catch { /* ignore cleanup errors */ }
-      this.transport = undefined;
+      this.transport = null;
       throw err;
     }
     this.connected = true;
@@ -85,7 +85,7 @@ export class McpClient {
     const isError = result.isError === true;
 
     // Handle structuredContent if present
-    if (result.structuredContent !== undefined && result.structuredContent !== null) {
+    if (result.structuredContent !== undefined) {
       return {
         content: JSON.stringify(result.structuredContent),
         isError,
@@ -96,7 +96,7 @@ export class McpClient {
     const textParts: string[] = [];
     if (Array.isArray(result.content)) {
       for (const block of result.content) {
-        if (typeof block === 'object' && block !== null && 'type' in block) {
+        if (typeof block === 'object' && block !== undefined && 'type' in block) {
           if (block.type === 'text' && 'text' in block) {
             textParts.push(String(block.text));
           } else if (block.type === 'resource' && 'resource' in block) {

package/src/memory/conversation-crud.ts

@@ -156,7 +156,27 @@ export function createConversation(titleOrOpts?: string | { title?: string; thre
     source,
     memoryScopeId,
   };
-  db.insert(conversations).values(conversation).run();
+
+  // Retry on SQLITE_BUSY and SQLITE_IOERR — transient disk I/O errors or WAL
+  // contention can cause the first attempt to fail even under normal load.
+  const MAX_RETRIES = 3;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      db.insert(conversations).values(conversation).run();
+      break;
+    } catch (err) {
+      const code = (err as { code?: string }).code ?? '';
+      if (attempt < MAX_RETRIES && (code.startsWith('SQLITE_BUSY') || code.startsWith('SQLITE_IOERR'))) {
+        log.warn({ attempt, conversationId: id, code }, 'createConversation: transient SQLite error, retrying');
+        // Synchronous sleep — createConversation is synchronous and the
+        // retry window is short (50-150ms), so Bun.sleepSync is appropriate.
+        Bun.sleepSync(50 * (attempt + 1));
+        continue;
+      }
+      throw err;
+    }
+  }
+
   return conversation;
 }
 
@@ -213,7 +233,8 @@ export async function addMessage(conversationId: string, role: string, content:
       ? metadata.userMessageChannel
       : null;
   // Wrap insert + updatedAt bump in a transaction so they're atomic.
-  // Retry on SQLITE_BUSY in case busy_timeout is exhausted under heavy contention.
+  // Retry on SQLITE_BUSY* and SQLITE_IOERR* — covers WAL contention variants
+  // (SQLITE_BUSY_SNAPSHOT, SQLITE_BUSY_RECOVERY) and transient disk I/O errors.
   // Timestamp is recomputed each attempt so a late retry doesn't persist a stale updatedAt.
   const MAX_RETRIES = 3;
   let now!: number;
@@ -243,8 +264,9 @@ export async function addMessage(conversationId: string, role: string, content:
       });
       break;
     } catch (err) {
-      if (attempt < MAX_RETRIES && (err as { code?: string }).code === 'SQLITE_BUSY') {
-        log.warn({ attempt, conversationId }, 'addMessage: SQLITE_BUSY, retrying');
+      const errCode = (err as { code?: string }).code ?? '';
+      if (attempt < MAX_RETRIES && (errCode.startsWith('SQLITE_BUSY') || errCode.startsWith('SQLITE_IOERR'))) {
+        log.warn({ attempt, conversationId, code: errCode }, 'addMessage: transient SQLite error, retrying');
         await Bun.sleep(50 * (attempt + 1));
         continue;
       }

package/src/memory/migrations/119-schema-indexes-and-columns.ts

@@ -1,4 +1,5 @@
 import type { DrizzleDb } from '../db-connection.js';
+import { getSqliteFrom } from '../db-connection.js';
 
 /**
  * Add indexes, a column, and a unique constraint for schema improvements:
@@ -15,23 +16,50 @@ export function migrateSchemaIndexesAndColumns(database: DrizzleDb): void {
     database.run(/*sql*/ `ALTER TABLE memory_jobs ADD COLUMN started_at INTEGER`);
   } catch { /* already exists */ }
 
-  // Deduplicate before creating the unique index — the prior schema allowed
-  // multiple rows per (notification_decision_id, channel) via the wider
-  // (decision_id, channel, destination, attempt) unique index.  Keep the
-  // row with the latest updated_at for each group.
-  database.run(/*sql*/ `
-    DELETE FROM notification_deliveries
-    WHERE id NOT IN (
-      SELECT id FROM (
-        SELECT id, ROW_NUMBER() OVER (
-          PARTITION BY notification_decision_id, channel
-          ORDER BY updated_at DESC
-        ) AS rn
-        FROM notification_deliveries
-      )
-      WHERE rn = 1
-    )
-  `);
+  // Ensure notification_decision_id column exists on notification_deliveries.
+  // Migration 114 (createNotificationTables) should have created this column,
+  // but on databases where 114 crashed mid-run the column may be absent. Rather
+  // than silently skipping the dedup+index step (leaving the schema incompatible
+  // with runtime code that writes notificationDecisionId), we add the column
+  // here if it is missing, then proceed unconditionally.
+  const raw = getSqliteFrom(database);
+  const notifDdl = raw.query(
+    `SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'notification_deliveries'`,
+  ).get() as { sql: string } | null;
 
-  database.run(/*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_notification_deliveries_decision_channel ON notification_deliveries(notification_decision_id, channel)`);
+  if (notifDdl && !notifDdl.sql.includes('notification_decision_id')) {
+    // ADD COLUMN cannot carry NOT NULL without a default in SQLite, so we add
+    // it as nullable TEXT. Existing rows get NULL, which is valid until the
+    // runtime backfills or replaces them. The unique index below is created
+    // with WHERE NOT NULL to tolerate the transition period.
+    try {
+      database.run(/*sql*/ `ALTER TABLE notification_deliveries ADD COLUMN notification_decision_id TEXT`);
+    } catch { /* column was added concurrently — safe to continue */ }
+  }
+
+  if (notifDdl) {
+    // Deduplicate before creating the unique index — the prior schema allowed
+    // multiple rows per (notification_decision_id, channel) via the wider
+    // (decision_id, channel, destination, attempt) unique index.  Keep the
+    // row with the latest updated_at for each group.
+    try {
+      database.run(/*sql*/ `
+        DELETE FROM notification_deliveries
+        WHERE id NOT IN (
+          SELECT id FROM (
+            SELECT id, ROW_NUMBER() OVER (
+              PARTITION BY notification_decision_id, channel
+              ORDER BY updated_at DESC
+            ) AS rn
+            FROM notification_deliveries
+          )
+          WHERE rn = 1
+        )
+      `);
+    } catch { /* deduplication failed — unique index creation below may fail too, which is non-fatal */ }
+
+    try {
+      database.run(/*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_notification_deliveries_decision_channel ON notification_deliveries(notification_decision_id, channel) WHERE notification_decision_id IS NOT NULL`);
+    } catch { /* index already exists or constraint violation — safe to continue */ }
+  }
 }

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

@@ -9,38 +9,13 @@ import type { ToolDefinition } from '../../providers/types.js';
 import { redactSecrets } from '../../security/secret-scanner.js';
 import { getLogger } from '../../util/logger.js';
 import { formatShellOutput } from '../shared/shell-output.js';
+import { buildSanitizedEnv } from '../terminal/safe-env.js';
 import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
 
 const log = getLogger('host-shell-tool');
 
-const SAFE_ENV_VARS = [
-  'PATH',
-  'HOME',
-  'TERM',
-  'LANG',
-  'EDITOR',
-  'SHELL',
-  'USER',
-  'TMPDIR',
-  'LC_ALL',
-  'LC_CTYPE',
-  'XDG_RUNTIME_DIR',
-  'DISPLAY',
-  'COLORTERM',
-  'TERM_PROGRAM',
-  'SSH_AUTH_SOCK',
-  'SSH_AGENT_PID',
-  'GPG_TTY',
-  'GNUPGHOME',
-] as const;
-
-function buildSanitizedEnv(): Record<string, string> {
-  const env: Record<string, string> = {};
-  for (const key of SAFE_ENV_VARS) {
-    if (process.env[key] != null) {
-      env[key] = process.env[key]!;
-    }
-  }
+function buildHostShellEnv(): Record<string, string> {
+  const env = buildSanitizedEnv();
   // Ensure ~/.local/bin and ~/.bun/bin are in PATH so `vellum` and `bun` are
   // always reachable, even when the daemon is launched from a macOS app
   // bundle that inherits a minimal PATH.
@@ -125,7 +100,7 @@ class HostShellTool implements Tool {
 
       const child = spawn('bash', ['-c', '--', command], {
         cwd: workingDir,
-        env: buildSanitizedEnv(),
+        env: buildHostShellEnv(),
         stdio: ['ignore', 'pipe', 'pipe'],
       });
 

package/src/tools/swarm/delegate.ts

@@ -8,6 +8,7 @@ import { executeSwarm } from '../../swarm/orchestrator.js';
 import { generatePlan } from '../../swarm/router-planner.js';
 import { getLogger } from '../../util/logger.js';
 import { truncate } from '../../util/truncate.js';
+import { registerTool } from '../registry.js';
 import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
 
 const log = getLogger('swarm-delegate');
@@ -178,6 +179,8 @@ export const swarmDelegateTool: Tool = {
   },
 };
 
+registerTool(swarmDelegateTool);
+
 /** Clear all active sessions — only for testing. */
 export function _resetSwarmActive(): void {
   activeSessions.clear();

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

@@ -5,6 +5,8 @@
  *
  * Shared by the sandbox bash tool and skill sandbox runner.
  */
+import { getGatewayInternalBaseUrl, getIngressPublicBaseUrl } from '../../config/env.js';
+
 const SAFE_ENV_VARS = [
   'PATH',
   'HOME',
@@ -33,5 +35,12 @@ export function buildSanitizedEnv(): Record<string, string> {
       env[key] = process.env[key]!;
     }
   }
+  // Always inject an internal gateway base for local control-plane/API calls.
+  const internalGatewayBase = getGatewayInternalBaseUrl();
+  env.INTERNAL_GATEWAY_BASE_URL = internalGatewayBase;
+  // Inject a public gateway base when ingress is configured; otherwise fall
+  // back to the internal base so commands remain functional in local-only mode.
+  const publicGatewayBase = getIngressPublicBaseUrl()?.replace(/\/+$/, '');
+  env.GATEWAY_BASE_URL = publicGatewayBase || internalGatewayBase;
   return env;
 }

package/src/tools/tool-manifest.ts

@@ -6,7 +6,6 @@
  * so adding/removing tools only requires editing this manifest.
  */
 
-import { RiskLevel } from '../permissions/types.js';
 import { accountManageTool } from './credentials/account-registry.js';
 import { credentialStoreTool } from './credentials/vault.js';
 import { memorySaveTool, memorySearchTool, memoryUpdateTool } from './memory/register.js';
@@ -20,22 +19,34 @@ import type { Tool } from './types.js';
 import { screenWatchTool } from './watch/screen-watch.js';
 
 // ── Eager side-effect modules ───────────────────────────────────────
-// Importing these modules triggers a top-level `registerTool()` call.
+// These static imports trigger top-level `registerTool()` side effects.
+//
+// IMPORTANT: These MUST be static imports (not dynamic `await import()`).
+// When the daemon is compiled with `bun --compile`, dynamic imports with
+// relative string literals resolve against the virtual `/$bunfs/root/`
+// filesystem root rather than the module's own directory, causing
+// "Cannot find module './filesystem/read.js'" crashes in production builds.
+// Static imports are resolved at bundle time and are always safe.
+import './assets/materialize.js';
+import './assets/search.js';
+import './filesystem/edit.js';
+import './filesystem/read.js';
+import './filesystem/view-image.js';
+import './filesystem/write.js';
+import './network/web-fetch.js';
+import './network/web-search.js';
+import './skills/delete-managed.js';
+import './skills/load.js';
+import './skills/scaffold-managed.js';
+import './swarm/delegate.js';
+import './system/request-permission.js';
+import './system/version.js';
+import './terminal/shell.js';
 
-export async function loadEagerModules(): Promise<void> {
-  await import('./filesystem/read.js');
-  await import('./filesystem/write.js');
-  await import('./filesystem/edit.js');
-  await import('./network/web-search.js');
-  await import('./network/web-fetch.js');
-  await import('./skills/load.js');
-  await import('./skills/scaffold-managed.js');
-  await import('./skills/delete-managed.js');
-  await import('./system/request-permission.js');
-  await import('./assets/search.js');
-  await import('./assets/materialize.js');
-  await import('./filesystem/view-image.js');
-  await import('./system/version.js');
+// loadEagerModules is a no-op now that all eager registrations happen via
+// static imports above. Kept for API compatibility with registry.ts callers.
+export function loadEagerModules(): Promise<void> {
+  return Promise.resolve();
 }
 
 // Tool names registered by the eager modules above.  Listed explicitly so
@@ -43,6 +54,7 @@ export async function loadEagerModules(): Promise<void> {
 // already in the registry before init ran (e.g. when a test file imports
 // an eager module at the top level).
 export const eagerModuleToolNames: string[] = [
+  'bash',
   'file_read',
   'file_write',
   'file_edit',
@@ -54,6 +66,7 @@ export const eagerModuleToolNames: string[] = [
   'request_system_permission',
   'asset_search',
   'asset_materialize',
+  'swarm_delegate',
   'view_image',
   'version',
 ];
@@ -78,76 +91,8 @@ export const explicitTools: Tool[] = [
 
 // ── Lazy tool descriptors ───────────────────────────────────────────
 // Tools that defer module loading until first invocation.
+// bash and swarm_delegate were previously lazy but are now eagerly registered
+// via side-effect imports above, preserving their full definitions (including
+// the `reason` field on bash) and fixing bun --compile module-not-found crashes.
 
-export const lazyTools: LazyToolDescriptor[] = [
-  {
-    name: 'bash',
-    description: 'Execute a shell command on the local machine',
-    category: 'terminal',
-    defaultRiskLevel: RiskLevel.Medium,
-    definition: {
-      name: 'bash',
-      description: 'Execute a shell command on the local machine',
-      input_schema: {
-        type: 'object',
-        properties: {
-          command: {
-            type: 'string',
-            description: 'The shell command to execute',
-          },
-          timeout_seconds: {
-            type: 'number',
-            description: 'Optional timeout in seconds. Defaults to the configured default (120s). Cannot exceed the configured maximum.',
-          },
-          network_mode: {
-            type: 'string',
-            enum: ['off', 'proxied'],
-            description: 'Network access mode for the command. "off" (default) blocks network access; "proxied" routes traffic through the credential proxy.',
-          },
-          credential_ids: {
-            type: 'array',
-            items: { type: 'string' },
-            description: 'Optional list of credential IDs to inject via the proxy when network_mode is "proxied".',
-          },
-        },
-        required: ['command'],
-      },
-    },
-    loader: async () => {
-      const mod = await import('./terminal/shell.js');
-      return mod.shellTool;
-    },
-  },
-  {
-    name: 'swarm_delegate',
-    description: 'Decompose a complex task into parallel specialist subtasks and execute them concurrently.',
-    category: 'orchestration',
-    defaultRiskLevel: RiskLevel.Medium,
-    definition: {
-      name: 'swarm_delegate',
-      description: 'Decompose a complex task into parallel specialist subtasks and execute them concurrently. Use this for multi-part tasks that benefit from parallel research, coding, and review.',
-      input_schema: {
-        type: 'object',
-        properties: {
-          objective: {
-            type: 'string',
-            description: 'The complex task to decompose and execute in parallel',
-          },
-          context: {
-            type: 'string',
-            description: 'Optional additional context about the task or codebase',
-          },
-          max_workers: {
-            type: 'number',
-            description: 'Maximum concurrent workers (1-6, default from config)',
-          },
-        },
-        required: ['objective'],
-      },
-    },
-    loader: async () => {
-      const mod = await import('./swarm/delegate.js');
-      return mod.swarmDelegateTool;
-    },
-  },
-];
+export const lazyTools: LazyToolDescriptor[] = [];