@vellumai/assistant 0.12.2-staging.5 → 0.12.2-staging.7

package/src/tools/skills/scaffold-managed.ts

@@ -49,9 +49,12 @@ const MISSING_CHANGE_SUMMARY =
 /**
  * Validate + normalize a string-array input (sanitize, drop blanks, dedupe).
  * Returns `{ error }` on the first invalid element, or `{ value }` holding
- * the normalized array (undefined when absent or empty). Shared by the
- * includes / activation_hints / avoid_when inputs so they behave identically;
- * whether an absent value is acceptable is the caller's call.
+ * the normalized array: undefined when the input is absent, and an empty
+ * array when it was passed empty, since on an overwrite the store keeps the
+ * current value for an absent field and clears it for an empty one. Shared by
+ * the includes / activation_hints / avoid_when inputs so they behave
+ * identically; whether an absent or empty value is acceptable is the
+ * caller's call.
  * Each element goes through sanitizeFrontmatterValue: activation_hints /
  * avoid_when are concatenated verbatim into capability memory text (see
  * buildSkillContent), so an embedded newline could otherwise smuggle an extra
@@ -84,7 +87,7 @@ function normalizeOptionalStringArray(
     seen.add(cleaned);
     normalized.push(cleaned);
   }
-  return { value: normalized.length > 0 ? normalized : undefined };
+  return { value: normalized };
 }
 
 /**
@@ -131,7 +134,8 @@ function notifyBackgroundSkillUpdate(args: {
     sourceEventName: "activity.complete",
     dedupeKey: `skill-updated:${args.skillId}:${day}`,
     contextPayload: {
-      // `summary` feeds the copy composer; `title`/`body` are the home feed's
+      // `summary` feeds the copy composer and `title` is the headline both
+      // it and the home feed keep; `title`/`body` are also the feed's
       // fallback when no channel copy was rendered. Without them a fully
       // suppressed delivery (the intended shape for this signal: low urgency,
       // background, no interruption) leaves the feed writer with no summary
@@ -231,9 +235,11 @@ export async function executeScaffoldManagedSkill(
     return { content: `Error: ${activationHintsResult.error}`, isError: true };
   }
   const activationHints = activationHintsResult.value;
-  // Hints are the skill's "Use when:" retrieval text, and scaffolding rewrites
-  // the whole SKILL.md, so a write without them leaves (or strips) none.
-  if (!activationHints) {
+  // Hints are the skill's "Use when:" retrieval text and should track the
+  // body, so every write states them: the store would keep the current ones
+  // on an overwrite, but hints for a rewritten procedure are the caller's
+  // to restate, not the store's to assume.
+  if (!activationHints || activationHints.length === 0) {
     return {
       content: `Error: ${MISSING_ACTIVATION_HINTS}`,
       isError: true,
@@ -313,8 +319,9 @@ export async function executeScaffoldManagedSkill(
   }
 
   // Validate and normalize the optional category (lowercased/trimmed for
-  // consistency with the lowercase Skills-UI sidebar buckets). Blank or
-  // whitespace-only values become undefined so they never land in frontmatter.
+  // consistency with the lowercase Skills-UI sidebar buckets). A blank value
+  // is passed through as the store's "clear" signal; the frontmatter builder
+  // never writes a blank category.
   let category: string | undefined;
   if (input.category !== undefined) {
     if (typeof input.category !== "string") {
@@ -323,10 +330,7 @@ export async function executeScaffoldManagedSkill(
         isError: true,
       };
     }
-    const normalized = input.category.trim().toLowerCase();
-    if (normalized) {
-      category = normalized;
-    }
+    category = input.category.trim().toLowerCase();
   }
 
   // The update notice's body. Model-authored text bound for a notification

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

@@ -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/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";
@@ -284,6 +288,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 +365,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/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).