@vellumai/assistant 0.12.2 → 0.12.3-staging.1

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

@@ -51,19 +51,19 @@ describe("safe-env Qdrant forwarding", () => {
 });
 
 describe("safe-env CES child forwarding", () => {
-  test("forwards CES HTTP credentials so sanitized children can resolve managed connections", () => {
+  test("forwards CES IPC discovery env and CES HTTP credentials", () => {
+    expect(SAFE_ENV_VARS).toContain("CES_BOOTSTRAP_SOCKET_DIR");
     expect(SAFE_ENV_VARS).toContain("CES_SERVICE_TOKEN");
     expect(SAFE_ENV_VARS).toContain("CES_CREDENTIAL_URL");
-    expect(SAFE_ENV_VARS).toContain("CES_LOCAL_SOCKET");
 
     const env = buildSanitizedEnv("linux", {
+      CES_BOOTSTRAP_SOCKET_DIR: "/run/ces-bootstrap",
       CES_SERVICE_TOKEN: "vault-bearer",
       CES_CREDENTIAL_URL: "http://127.0.0.1:8090",
-      CES_LOCAL_SOCKET: "/tmp/ces.sock",
     });
+    expect(env.CES_BOOTSTRAP_SOCKET_DIR).toBe("/run/ces-bootstrap");
     expect(env.CES_SERVICE_TOKEN).toBe("vault-bearer");
     expect(env.CES_CREDENTIAL_URL).toBe("http://127.0.0.1:8090");
-    expect(env.CES_LOCAL_SOCKET).toBe("/tmp/ces.sock");
   });
 });
 
@@ -111,6 +111,35 @@ describe("safe-env Windows forwarding", () => {
     }
   });
 
+  test("prepends the Windows assistant binary directory when it sits beside the runtime", () => {
+    const dir = mkdtempSync(join(tmpdir(), "win-assistant-"));
+    writeFileSync(join(dir, "assistant.exe"), "");
+    try {
+      const env = buildSanitizedEnv(
+        "win32",
+        { Path: "C:\\Windows\\System32" },
+        { execPath: join(dir, "vellum-daemon.exe") },
+      );
+      expect(env.PATH).toBe(`${dir};C:\\Windows\\System32`);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("does not invent a Windows assistant path when the sibling binary is absent", () => {
+    const dir = mkdtempSync(join(tmpdir(), "win-no-assistant-"));
+    try {
+      const env = buildSanitizedEnv(
+        "win32",
+        { Path: "C:\\Windows\\System32" },
+        { execPath: join(dir, "vellum-daemon.exe") },
+      );
+      expect(env.PATH).toBe("C:\\Windows\\System32");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
   test("matches Windows environment names case-insensitively", () => {
     const windowsEnv = buildSanitizedEnv("win32", {
       Path: "C:\\Windows\\System32;C:\\Program Files\\Vellum",

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

@@ -4,7 +4,6 @@ import { runSanitizedBash } from "../sanitized-bash.js";
 
 describe("runSanitizedBash", () => {
   const priorToken = process.env.CES_SERVICE_TOKEN;
-  const priorSocket = process.env.CES_LOCAL_SOCKET;
 
   afterEach(() => {
     if (priorToken == null) {
@@ -12,11 +11,6 @@ describe("runSanitizedBash", () => {
     } else {
       process.env.CES_SERVICE_TOKEN = priorToken;
     }
-    if (priorSocket == null) {
-      delete process.env.CES_LOCAL_SOCKET;
-    } else {
-      process.env.CES_LOCAL_SOCKET = priorSocket;
-    }
   });
 
   test("runs a command and returns stdout", async () => {
@@ -35,14 +29,6 @@ describe("runSanitizedBash", () => {
     expect(result.stdout.trim()).toBe("vault-bearer");
   });
 
-  test("forwards CES_LOCAL_SOCKET to the child", async () => {
-    process.env.CES_LOCAL_SOCKET = "/tmp/ces.sock";
-    const result = await runSanitizedBash("printenv CES_LOCAL_SOCKET", 5_000);
-    expect(result.error).toBeUndefined();
-    expect(result.exitCode).toBe(0);
-    expect(result.stdout.trim()).toBe("/tmp/ces.sock");
-  });
-
   test("times out a hung command", async () => {
     const result = await runSanitizedBash("sleep 5", 200);
     expect(result.error).toBeUndefined();

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

@@ -7,8 +7,12 @@
  */
 import { readdirSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
 
-import { pathListDelimiter } from "@vellumai/environments/shell";
+import {
+  pathListDelimiter,
+  prependUniquePathEntries,
+} from "@vellumai/environments/shell";
 
 import { getGatewayInternalBaseUrl } from "../../config/env.js";
 import { getDataDir, getWorkspaceDir } from "../../util/platform.js";
@@ -55,34 +59,16 @@ export const SAFE_ENV_VARS = [
   "VELLUM_MIGRATION_EXPORT_ALLOWED_HOSTS",
   "VELLUM_MIGRATION_IMPORT_ALLOWED_HOSTS",
   "CES_MANAGED_MODE",
-  "CES_LOCAL_SOCKET",
-  // Child processes (bash, skill sandbox, scheduled scripts) run
-  // `assistant oauth request` in-process and resolve managed connections
-  // through CES HTTP (`getSecureKeyAsync` / platform client). They need
-  // both the credential URL and the service token. CES_LOCAL_SOCKET alone
-  // is not enough on managed pods: the socket is often absent or does not
-  // complete the lazy RPC path those children use, so a connected account
-  // looks disconnected from sanitized children while the daemon still
-  // reports healthy.
-  //
-  // To drop these later, children must resolve the same ACTIVE managed
-  // connections without inheriting a reusable vault bearer. That means
-  // CES RPC over CES_LOCAL_SOCKET works on managed pods (present,
-  // reachable, and sufficient for secure-key / platform-client reads), or
-  // a narrower grant protocol issues a one-shot provider token.
-  //
-  // Before removing them again, reproduce from a sanitized child on a
-  // platform-managed pod. After `buildSanitizedEnv()`,
-  // `assistant oauth request --provider <key> --json <provider-url>` must
-  // succeed for an ACTIVE connection and match a direct terminal
-  // invocation. Unit tests that only assert the vars are absent are not
-  // enough: also cover skill sandbox and scheduled-script children.
   "CES_CREDENTIAL_URL",
   "CES_SERVICE_TOKEN",
+  // Child processes (bash, skill sandbox, scheduled scripts) reach CES
+  // over IPC via `CES_BOOTSTRAP_SOCKET_DIR`. CES HTTP credentials are
+  // forwarded so children can fail over to CES HTTP while that transport
+  // still exists.
   // Per-instance port of the assistant-managed Qdrant sidecar, so skill and
   // bash-tool subprocesses that use the vector helpers (e.g. embed/search over
   // `@vellumai/plugin-api`) resolve the same local sidecar as the daemon
-  // (127.0.0.1:<port>). `QDRANT_URL` is intentionally excluded — it flips
+  // (127.0.0.1:<port>). `QDRANT_URL` is intentionally excluded: it flips
   // QdrantManager into external mode and bypasses the local managed lifecycle.
   "QDRANT_HTTP_PORT",
   "IS_CONTAINERIZED",
@@ -284,6 +270,7 @@ function appendUniquePathEntries(
 export function buildSanitizedEnv(
   hostPlatform: NodeJS.Platform = process.platform,
   sourceEnv: NodeJS.ProcessEnv = process.env,
+  options?: { execPath?: string },
 ): Record<string, string> {
   const env: Record<string, string> = {};
   const isKataRuntime = isKataFamilyRuntime(sourceEnv.VELLUM_SANDBOX_RUNTIME);
@@ -360,5 +347,29 @@ export function buildSanitizedEnv(
   if (!env.LC_ALL) {
     env.LC_ALL = utf8Locale;
   }
+  prependWindowsAssistantDir(
+    env,
+    hostPlatform,
+    options?.execPath ?? process.execPath,
+  );
   return env;
 }
+
+function prependWindowsAssistantDir(
+  env: Record<string, string>,
+  hostPlatform: NodeJS.Platform,
+  execPath: string,
+): void {
+  if (hostPlatform !== "win32") {
+    return;
+  }
+  const execDir = dirname(execPath);
+  try {
+    if (!statSync(join(execDir, "assistant.exe")).isFile()) {
+      return;
+    }
+  } catch {
+    return;
+  }
+  env.PATH = prependUniquePathEntries(env.PATH, [execDir], hostPlatform);
+}

package/src/tools/terminal/sanitized-bash.ts

@@ -11,9 +11,12 @@ import { spawn } from "node:child_process";
 
 import {
   buildShellInvocation,
+  buildShellSpawnFlags,
   terminateProcessTree,
+  watchShellProcessStart,
 } from "../../util/host-process.js";
 import { getWorkspaceDir } from "../../util/platform.js";
+import { SHELL_DID_NOT_START_MESSAGE } from "../shared/shell-output.js";
 import { buildSanitizedEnv } from "./safe-env.js";
 
 export const DEFAULT_SANITIZED_BASH_TIMEOUT_MS = 30_000;
@@ -63,10 +66,10 @@ export function runSanitizedBash(
     const child = spawn(wrapped.command, wrapped.args, {
       cwd: getWorkspaceDir(),
       stdio: ["ignore", "pipe", "pipe"],
-      detached: true,
       env: buildSanitizedEnv(),
-      windowsHide: true,
+      ...buildShellSpawnFlags(),
     });
+    const launch = watchShellProcessStart(child);
 
     const timer = setTimeout(() => {
       timedOut = true;
@@ -83,6 +86,16 @@ export function runSanitizedBash(
 
     child.on("close", (code) => {
       clearTimeout(timer);
+      if (!launch.didStart()) {
+        finish({
+          stdout: "",
+          stderr: "",
+          exitCode: null,
+          timedOut: false,
+          error: SHELL_DID_NOT_START_MESSAGE,
+        });
+        return;
+      }
       finish({
         stdout: Buffer.concat(stdoutChunks).toString(),
         stderr: Buffer.concat(stderrChunks).toString(),

package/src/tools/terminal/shell-launch.test.ts

@@ -0,0 +1,162 @@
+import * as realChildProcess from "node:child_process";
+import { EventEmitter } from "node:events";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { setConfig } from "../../__tests__/helpers/set-config.js";
+import { SHELL_DID_NOT_START_MESSAGE } from "../shared/shell-output.js";
+import type { ToolContext } from "../types.js";
+
+const originalSpawn = realChildProcess.spawn;
+
+type FakeChild = EventEmitter & {
+  pid?: number;
+  stdout: EventEmitter;
+  stderr: EventEmitter;
+  kill: () => boolean;
+};
+
+type SpawnImpl = (
+  ...args: Parameters<typeof realChildProcess.spawn>
+) => ReturnType<typeof realChildProcess.spawn>;
+
+const spawnCalls: {
+  command: string;
+  args: unknown;
+  options: realChildProcess.SpawnOptions;
+}[] = [];
+
+let spawnImpl: SpawnImpl = originalSpawn as SpawnImpl;
+
+const spawnSpy = mock((...args: Parameters<typeof realChildProcess.spawn>) => {
+  spawnCalls.push({
+    command: args[0] as string,
+    args: args[1],
+    options: (args[2] ?? {}) as realChildProcess.SpawnOptions,
+  });
+  return spawnImpl(...args);
+});
+
+mock.module("node:child_process", () => ({
+  ...realChildProcess,
+  spawn: spawnSpy,
+}));
+
+const realLogger = await import("../../util/logger.js");
+mock.module("../../util/logger.js", () => ({
+  ...realLogger,
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+setConfig("timeouts", { shellDefaultTimeoutSec: 30, shellMaxTimeoutSec: 60 });
+
+const realHub = await import("../../runtime/assistant-event-hub.js");
+mock.module("../../runtime/assistant-event-hub.js", () => ({
+  ...realHub,
+  broadcastMessage: () => {},
+}));
+
+const realWake = await import("../../runtime/agent-wake.js");
+mock.module("../../runtime/agent-wake.js", () => ({
+  ...realWake,
+  wakeAgentForOpportunity: async () => ({}),
+}));
+
+const { shellTool } = await import("./shell.js");
+
+function makeContext(workingDir: string): ToolContext {
+  return {
+    workingDir,
+    conversationId: "conv-xyz",
+    trustClass: "guardian",
+  };
+}
+
+function fakeChild(): FakeChild {
+  const child = new EventEmitter() as FakeChild;
+  child.stdout = new EventEmitter();
+  child.stderr = new EventEmitter();
+  child.kill = () => true;
+  return child;
+}
+
+function closeWithoutStart(): ReturnType<typeof realChildProcess.spawn> {
+  const child = fakeChild();
+  queueMicrotask(() => {
+    child.emit("close", 0, null);
+  });
+  return child as unknown as ReturnType<typeof realChildProcess.spawn>;
+}
+
+function spawnError(
+  err: NodeJS.ErrnoException,
+): ReturnType<typeof realChildProcess.spawn> {
+  const child = fakeChild();
+  queueMicrotask(() => {
+    child.emit("error", err);
+  });
+  return child as unknown as ReturnType<typeof realChildProcess.spawn>;
+}
+
+describe("bash launch failures are not success", () => {
+  let workingDir = "";
+
+  beforeEach(() => {
+    spawnCalls.length = 0;
+    spawnImpl = originalSpawn as SpawnImpl;
+    workingDir = mkdtempSync(join(tmpdir(), "bash-launch-"));
+  });
+
+  afterEach(() => {
+    spawnImpl = originalSpawn as SpawnImpl;
+    rmSync(workingDir, { recursive: true, force: true });
+  });
+
+  test("a close with exit 0 and no process start is an error, not command_completed", async () => {
+    spawnImpl = () => closeWithoutStart();
+    const proof = join(workingDir, "proof.txt");
+
+    const result = await shellTool.execute(
+      {
+        command: "printf ran > proof.txt",
+        activity: "test",
+      },
+      makeContext(workingDir),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toBe(SHELL_DID_NOT_START_MESSAGE);
+    expect(result.content).not.toContain("<command_completed />");
+    expect(existsSync(proof)).toBe(false);
+    expect(spawnCalls).toHaveLength(1);
+  });
+
+  test("a failed spawn of the shell is an error", async () => {
+    spawnImpl = () => {
+      const err = new Error(
+        "spawn powershell.exe ENOENT",
+      ) as NodeJS.ErrnoException;
+      err.code = "ENOENT";
+      return spawnError(err);
+    };
+
+    const result = await shellTool.execute(
+      {
+        command: "assistant browser --help",
+        activity: "test",
+      },
+      makeContext(workingDir),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("Error spawning command");
+    expect(result.content).toContain("The command was not found");
+    expect(result.content).not.toContain("<command_completed />");
+    expect(existsSync(join(workingDir, "help.txt"))).toBe(false);
+  });
+});

package/src/tools/terminal/shell.test.ts

@@ -7,6 +7,7 @@ import { setConfig } from "../../__tests__/helpers/set-config.js";
 import {
   MAX_OUTPUT_LENGTH,
   OUTPUT_TRUNCATED_TAG,
+  SHELL_DID_NOT_START_MESSAGE,
 } from "../shared/shell-output.js";
 import type { ToolContext } from "../types.js";
 
@@ -207,6 +208,34 @@ describe("foreground stdin handling", () => {
   });
 });
 
+describe("foreground command execution", () => {
+  let tmpDir = "";
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "bash-exec-"));
+  });
+
+  afterEach(async () => {
+    if (tmpDir) {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("a command that writes a file must actually create it", async () => {
+    const result = await shellTool.execute(
+      {
+        command: "printf ran > proof.txt",
+        activity: "test",
+      },
+      { ...makeContext(), workingDir: tmpDir },
+    );
+
+    expect(result.isError).toBeFalsy();
+    expect(result.content).not.toBe(SHELL_DID_NOT_START_MESSAGE);
+    expect(await readFile(join(tmpDir, "proof.txt"), "utf-8")).toBe("ran");
+  });
+});
+
 describe("streaming stdout cap", () => {
   let tmpDir = "";
 

package/src/tools/terminal/shell.ts

@@ -11,7 +11,9 @@ import { conversationRevealNonce } from "../../runtime/reveal-nonce.js";
 import { redactSecrets } from "../../security/secret-scanner.js";
 import {
   buildShellInvocation,
+  buildShellSpawnFlags,
   terminateProcessTree,
+  watchShellProcessStart,
 } from "../../util/host-process.js";
 import { getLogger } from "../../util/logger.js";
 import { getDataDir } from "../../util/platform.js";
@@ -324,9 +326,9 @@ export const shellTool = {
         cwd: context.workingDir,
         env,
         stdio: ["ignore", "pipe", "pipe"],
-        detached: true,
-        windowsHide: true,
+        ...buildShellSpawnFlags(),
       });
+      const launch = watchShellProcessStart(child);
       const collector = attachBoundedStdio(child);
 
       const killTree = buildKillTree(child, {
@@ -367,11 +369,13 @@ export const shellTool = {
           timedOut,
         });
 
-        const fmtResult = collector.format(code, timedOut, timeoutSec);
+        const fmtResult = collector.format(code, timedOut, timeoutSec, {
+          started: launch.didStart(),
+        });
 
         const status: BackgroundToolCompletedEvent["status"] = aborted
           ? "cancelled"
-          : timedOut
+          : timedOut || fmtResult.isError
             ? "failed"
             : code === 0
               ? "completed"
@@ -529,9 +533,9 @@ export const shellTool = {
         cwd: context.workingDir,
         env,
         stdio: ["ignore", "pipe", "pipe"],
-        detached: true,
-        windowsHide: true,
+        ...buildShellSpawnFlags(),
       });
+      const launch = watchShellProcessStart(child);
       const collector = attachBoundedStdio(child, {
         onOutput: context.onOutput,
       });
@@ -573,7 +577,9 @@ export const shellTool = {
           timedOut,
         });
 
-        const fmtResult = collector.format(code, timedOut, timeoutSec);
+        const fmtResult = collector.format(code, timedOut, timeoutSec, {
+          started: launch.didStart(),
+        });
 
         resolve({
           content: fmtResult.content,

package/src/util/browser-human-verification.ts

@@ -0,0 +1,14 @@
+export const HUMAN_VERIFICATION_GUIDANCE =
+  "CAPTCHAs and bot-detection challenges must be completed by the user. " +
+  "This includes drag-to-verify sliders, press-and-hold checks, verification checkboxes and image puzzles. " +
+  "Stop before attempting the challenge, even when its controls look easy to automate. " +
+  "Do not click, drag, hold, script or retry the verification yourself.";
+
+export const DESKTOP_HELP_GUIDANCE =
+  HUMAN_VERIFICATION_GUIDANCE +
+  " In the virtual desktop, immediately call ask_question with " +
+  "desktopHelp: { message, doneLabel, skipLabel } in the user's language. " +
+  "Keep message to one short sentence explaining the needed human action. " +
+  "This shows an inline preview with Step In, Done and Skip. Wait for the response. " +
+  "After Done, inspect a fresh snapshot. If verification remains, request help again. " +
+  "Skip leaves the challenge unresolved. Use the same desktopHelp request for other steps that require direct user interaction.";

package/src/util/host-process.test.ts

@@ -1,6 +1,7 @@
+import { EventEmitter } from "node:events";
 import { expect, mock, test } from "bun:test";
 
-import { terminateProcessTree } from "./host-process.js";
+import { terminateProcessTree, watchShellProcessStart } from "./host-process.js";
 
 test("Windows process trees use taskkill and fall back to the direct child", () => {
   const kill = mock(() => true);
@@ -15,3 +16,18 @@ test("Windows process trees use taskkill and fall back to the direct child", ()
   expect(kill).toHaveBeenCalledTimes(1);
   expect(kill).toHaveBeenCalledWith();
 });
+
+test("watchShellProcessStart is false until spawn or a pid appears", () => {
+  const child = new EventEmitter() as EventEmitter & { pid?: number };
+  const launch = watchShellProcessStart(child);
+  expect(launch.didStart()).toBe(false);
+
+  child.emit("spawn");
+  expect(launch.didStart()).toBe(true);
+});
+
+test("watchShellProcessStart treats a pid assigned at construction as started", () => {
+  const child = new EventEmitter() as EventEmitter & { pid?: number };
+  child.pid = 4242;
+  expect(watchShellProcessStart(child).didStart()).toBe(true);
+});

package/src/util/host-process.ts

@@ -2,10 +2,34 @@ import { spawn } from "node:child_process";
 
 export {
   buildShellInvocation,
+  buildShellSpawnFlags,
   pathListDelimiter,
   prependUniquePathEntries,
 } from "@vellumai/environments/shell";
 
+export interface ShellProcessStartWatch {
+  didStart(): boolean;
+}
+
+/**
+ * Record whether a spawned child actually started. A `close` with exit 0 and
+ * empty stdio is not proof of execution: Windows can emit that when the
+ * process was never created. Callers must treat `didStart() === false` as a
+ * launch failure.
+ */
+export function watchShellProcessStart(child: {
+  pid?: number;
+  once(event: "spawn", listener: () => void): unknown;
+}): ShellProcessStartWatch {
+  let spawnSeen = child.pid != null;
+  child.once("spawn", () => {
+    spawnSeen = true;
+  });
+  return {
+    didStart: () => spawnSeen || child.pid != null,
+  };
+}
+
 export interface KillableProcess {
   pid?: number;
   kill: unknown;

package/src/util/unicode.ts

@@ -67,6 +67,35 @@ export function safeStringSlice(
   return str.slice(safeStart, safeEnd);
 }
 
+/**
+ * A `[start, end)` character window of at most `maxChars` code units that
+ * never splits a surrogate pair, for paging through text by offset. A split
+ * leaves a lone half at each edge, and each encodes to U+FFFD, so the
+ * character is lost from both this window and the next one paged in after
+ * it. `charCodeAt` reads the underlying text so a caller need not hold it as
+ * one string.
+ */
+export function surrogateSafeWindow(
+  total: number,
+  charCodeAt: (index: number) => number,
+  requestedStart: number,
+  maxChars: number,
+): { start: number; end: number } {
+  let start = Math.max(0, Math.min(requestedStart, total));
+  if (start > 0 && start < total && isLowSurrogate(charCodeAt(start))) {
+    start -= 1;
+  }
+
+  let end = Math.min(total, start + maxChars);
+  if (end > start && end < total && isHighSurrogate(charCodeAt(end - 1))) {
+    // Backing off would empty a one-character window, which stalls paging on
+    // the same offset, so take the whole pair instead.
+    end = end - 1 > start ? end - 1 : Math.min(total, end + 1);
+  }
+
+  return { start, end };
+}
+
 /**
  * Replace every orphaned UTF-16 surrogate in `str` with U+FFFD
  * (REPLACEMENT CHARACTER).