@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

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

@@ -17,6 +17,42 @@ function sanitizeFrontmatterValue(value: string): string {
   return value.replace(/[\r\n]+/g, " ").trim();
 }
 
+/**
+ * Validate + normalize an optional string-array input (sanitize, drop blanks,
+ * dedupe). Returns `{ error }` on the first invalid element, or `{ value }`
+ * holding the normalized array (undefined when empty). Shared by the
+ * includes / activation_hints / avoid_when inputs so they behave identically.
+ * 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
+ * prompt line into a future turn — collapse control chars the same way
+ * name/description are.
+ */
+function normalizeOptionalStringArray(
+  raw: unknown,
+  field: string,
+): { value?: string[]; error?: string } {
+  if (raw === undefined) return {};
+  if (!Array.isArray(raw)) {
+    return { error: `${field} must be an array of strings` };
+  }
+  const normalized: string[] = [];
+  const seen = new Set<string>();
+  for (const item of raw) {
+    if (typeof item !== "string") {
+      return { error: `each element in ${field} must be a non-empty string` };
+    }
+    const cleaned = sanitizeFrontmatterValue(item);
+    if (!cleaned) {
+      return { error: `each element in ${field} must be a non-empty string` };
+    }
+    if (seen.has(cleaned)) continue;
+    seen.add(cleaned);
+    normalized.push(cleaned);
+  }
+  return { value: normalized.length > 0 ? normalized : undefined };
+}
+
 /**
  * Core execution logic for scaffold_managed_skill.
  * Exported so bundled-skill executors and tests can call it directly.
@@ -63,41 +99,35 @@ export async function executeScaffoldManagedSkill(
     };
   }
 
-  // Validate and normalize includes
-  let includes: string[] | undefined;
-  if (input.includes !== undefined) {
-    if (!Array.isArray(input.includes)) {
-      return {
-        content: "Error: includes must be an array of strings",
-        isError: true,
-      };
-    }
-    for (const item of input.includes) {
-      if (typeof item !== "string") {
-        return {
-          content: "Error: each element in includes must be a non-empty string",
-          isError: true,
-        };
-      }
-      if (!item.trim()) {
-        return {
-          content: "Error: each element in includes must be a non-empty string",
-          isError: true,
-        };
-      }
-    }
-    const normalized: string[] = [];
-    const seen = new Set<string>();
-    for (const item of input.includes as string[]) {
-      const trimmed = item.trim();
-      if (seen.has(trimmed)) continue;
-      seen.add(trimmed);
-      normalized.push(trimmed);
-    }
-    if (normalized.length > 0) {
-      includes = normalized;
-    }
+  // Validate and normalize the optional string-array inputs. `includes` lists
+  // child skill IDs; activation_hints / avoid_when become the skill's
+  // "Use when:" / "Avoid when:" retrieval signal in memory.
+  const includesResult = normalizeOptionalStringArray(
+    input.includes,
+    "includes",
+  );
+  if (includesResult.error) {
+    return { content: `Error: ${includesResult.error}`, isError: true };
+  }
+  const includes = includesResult.value;
+
+  const activationHintsResult = normalizeOptionalStringArray(
+    input.activation_hints,
+    "activation_hints",
+  );
+  if (activationHintsResult.error) {
+    return { content: `Error: ${activationHintsResult.error}`, isError: true };
+  }
+  const activationHints = activationHintsResult.value;
+
+  const avoidWhenResult = normalizeOptionalStringArray(
+    input.avoid_when,
+    "avoid_when",
+  );
+  if (avoidWhenResult.error) {
+    return { content: `Error: ${avoidWhenResult.error}`, isError: true };
   }
+  const avoidWhen = avoidWhenResult.value;
 
   // Validate and normalize companion files
   let files: Array<{ path: string; content: string }> | undefined;
@@ -211,6 +241,8 @@ export async function executeScaffoldManagedSkill(
         : undefined,
     overwrite: input.overwrite === true,
     includes,
+    activationHints,
+    avoidWhen,
     category,
     files,
     author,

package/src/tools/skills/skill-script-runner.ts

@@ -48,6 +48,23 @@ export async function runSkillToolScript(
     });
   }
 
+  // Host execution dynamically imports the executor into the daemon process —
+  // full host code execution with no sandbox boundary. This is a first-party
+  // capability reserved for bundled skills, which ship trusted, in-repo
+  // executors. A non-bundled skill (managed, workspace, plugin, extra) that
+  // declares `execution_target: host` must be refused: otherwise an
+  // attacker-planted TOOLS.json — e.g. written into a managed skill dir via
+  // scaffold_managed_skill companion files, or shipped in a third-party skill —
+  // could get arbitrary code imported into the host process and auto-approved
+  // under the low-risk threshold. Non-bundled skills must run their tools in the
+  // sandbox (handled above); host execution here is a hard, fail-closed deny.
+  if (options?.target === "host" && !options?.bundled) {
+    return {
+      content: `Skill tool "${executorPath}" requests host execution, which is only permitted for first-party bundled skills. Non-bundled skills must declare execution_target: "sandbox".`,
+      isError: true,
+    };
+  }
+
   const scriptPath = resolve(join(skillDir, executorPath));
   const resolvedSkillDir = resolve(skillDir) + "/";
   if (!scriptPath.startsWith(resolvedSkillDir)) {

package/src/tools/skills/skill-tool-factory.ts

@@ -2,6 +2,7 @@ import type { SkillToolEntry } from "../../config/skills.js";
 import { RiskLevel } from "../../permissions/types.js";
 import {
   coerceStringBooleans,
+  coerceStringNumbers,
   validateInputAgainstSchema,
 } from "../../skills/validate-input.js";
 import type {
@@ -46,7 +47,10 @@ export function createSkillTool(
       context: ToolContext,
     ): Promise<ToolExecutionResult> {
       const schema = entry.input_schema as Record<string, unknown> | undefined;
-      const coercedInput = coerceStringBooleans(input, schema);
+      const coercedInput = coerceStringNumbers(
+        coerceStringBooleans(input, schema),
+        schema,
+      );
       const validation = validateInputAgainstSchema(
         entry.name,
         coercedInput,

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

@@ -29,6 +29,8 @@ export const SAFE_ENV_VARS = [
   "GNUPGHOME",
   "VELLUM_DEV",
   "VELLUM_DEBUG",
+  "VELLUM_SLOW_SYNC_THRESHOLD_MS",
+  "VELLUM_SLOW_QUERY_THRESHOLD_MS",
   "VELLUM_DEVICE_ID",
   "VELLUM_DISABLE_PLATFORM",
   "VELLUM_ENVIRONMENT",
@@ -43,6 +45,7 @@ export const SAFE_ENV_VARS = [
   "VELLUM_PLATFORM_URL",
   "VELLUM_ASSISTANT_PLATFORM_URL",
   "VELLUM_DOCS_BASE_URL",
+  "VELLUM_MIGRATION_IMPORT_ALLOWED_HOSTS",
   "CES_CREDENTIAL_URL",
   "CES_MANAGED_MODE",
   "IS_CONTAINERIZED",

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

@@ -0,0 +1,177 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { ToolContext } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Singleton mocks — must precede the tool import so bun's module mock applies.
+// ---------------------------------------------------------------------------
+
+// Silence the logger across every module this graph reaches.
+const realLogger = await import("../../util/logger.js");
+mock.module("../../util/logger.js", () => ({
+  ...realLogger,
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+const realLoader = await import("../../config/loader.js");
+mock.module("../../config/loader.js", () => ({
+  ...realLoader,
+  getConfig: () =>
+    ({
+      timeouts: { shellDefaultTimeoutSec: 30, shellMaxTimeoutSec: 60 },
+    }) as unknown as ReturnType<typeof realLoader.getConfig>,
+}));
+
+const realGates = await import("../../credential-execution/feature-gates.js");
+mock.module("../../credential-execution/feature-gates.js", () => ({
+  ...realGates,
+  isCesShellLockdownEnabled: () => false,
+}));
+
+// Capture lifecycle events broadcast by the tool.
+type CapturedEvent = { type: string } & Record<string, unknown>;
+const events: CapturedEvent[] = [];
+
+const realHub = await import("../../runtime/assistant-event-hub.js");
+mock.module("../../runtime/assistant-event-hub.js", () => ({
+  ...realHub,
+  broadcastMessage: (msg: unknown) => {
+    events.push(msg as CapturedEvent);
+  },
+}));
+
+// Background completion wakes the agent; that side-effect is out of scope here.
+const realWake = await import("../../runtime/agent-wake.js");
+mock.module("../../runtime/agent-wake.js", () => ({
+  ...realWake,
+  wakeAgentForOpportunity: async () => ({}),
+}));
+
+const { shellTool } = await import("./shell.js");
+const { cancelBackgroundTool, _clearRegistryForTesting } =
+  await import("../background-tool-registry.js");
+
+function makeContext(): ToolContext {
+  return {
+    workingDir: process.cwd(),
+    conversationId: "conv-1",
+    trustClass: "guardian",
+  };
+}
+
+async function waitFor(
+  predicate: () => boolean,
+  timeoutMs = 5000,
+): Promise<void> {
+  const start = Date.now();
+  while (!predicate()) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error("timed out waiting for condition");
+    }
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
+async function startBackground(command: string): Promise<string> {
+  const result = await shellTool.execute(
+    { command, activity: "test", background: true },
+    makeContext(),
+  );
+  const parsed = JSON.parse(result.content) as { id: string };
+  return parsed.id;
+}
+
+function completedEvents(): CapturedEvent[] {
+  return events.filter((e) => e.type === "background_tool_completed");
+}
+
+describe("background bash lifecycle events", () => {
+  beforeEach(() => {
+    events.length = 0;
+    _clearRegistryForTesting();
+  });
+
+  afterEach(() => {
+    _clearRegistryForTesting();
+  });
+
+  test("normal exit broadcasts one started then one completed", async () => {
+    const id = await startBackground("exit 0");
+
+    const started = events.filter((e) => e.type === "background_tool_started");
+    expect(started).toHaveLength(1);
+    expect(started[0]).toMatchObject({
+      id,
+      toolName: "bash",
+      conversationId: "conv-1",
+      command: "exit 0",
+    });
+    expect(typeof started[0]?.startedAt).toBe("number");
+
+    await waitFor(() => completedEvents().length > 0);
+    const completed = completedEvents();
+    expect(completed).toHaveLength(1);
+    expect(completed[0]).toMatchObject({
+      id,
+      conversationId: "conv-1",
+      status: "completed",
+      exitCode: 0,
+    });
+  });
+
+  test("non-zero exit broadcasts completed with status failed", async () => {
+    const id = await startBackground("exit 3");
+
+    await waitFor(() => completedEvents().length > 0);
+    const completed = completedEvents();
+    expect(completed).toHaveLength(1);
+    expect(completed[0]).toMatchObject({
+      id,
+      status: "failed",
+      exitCode: 3,
+    });
+  });
+
+  test("timed-out background command broadcasts completed with status failed", async () => {
+    // A 1s timeout against a long-running command forces the timeout watcher
+    // to SIGKILL the process group (timedOut=true, aborted=false), which must
+    // map to "failed" — distinct from a cancel's "cancelled".
+    const result = await shellTool.execute(
+      {
+        command: "sleep 30",
+        activity: "test",
+        background: true,
+        timeout_seconds: 1,
+      },
+      makeContext(),
+    );
+    const { id } = JSON.parse(result.content) as { id: string };
+
+    await waitFor(() => completedEvents().length > 0);
+    const completed = completedEvents();
+    expect(completed).toHaveLength(1);
+    expect(completed[0]).toMatchObject({ id, status: "failed" });
+    expect(completed[0]?.exitCode).toBeNull();
+    // A timeout is not a cancel: it must not carry the cancellation message.
+    expect(completed[0]?.output).not.toContain("cancelled");
+  });
+
+  test("cancelled background command broadcasts completed with status cancelled", async () => {
+    const id = await startBackground("sleep 30");
+
+    expect(completedEvents()).toHaveLength(0);
+    expect(cancelBackgroundTool(id)).toBe(true);
+
+    await waitFor(() => completedEvents().length > 0);
+    const completed = completedEvents();
+    expect(completed).toHaveLength(1);
+    expect(completed[0]).toMatchObject({ id, status: "cancelled" });
+    expect(completed[0]?.exitCode).toBeNull();
+    // Cancellation must not surface the "failed exit code null" framing.
+    expect(completed[0]?.output).toContain("cancelled");
+    expect(completed[0]?.output).not.toContain("failed");
+  });
+});

package/src/tools/terminal/shell.ts

@@ -3,16 +3,20 @@ import { spawn } from "node:child_process";
 
 import { getConfig } from "../../config/loader.js";
 import { isCesShellLockdownEnabled } from "../../credential-execution/feature-gates.js";
+import type { BackgroundToolCompleted } from "../../daemon/message-types/background-tools.js";
 import { RiskLevel } from "../../permissions/types.js";
 import { wakeAgentForOpportunity } from "../../runtime/agent-wake.js";
+import { broadcastMessage } from "../../runtime/assistant-event-hub.js";
 import { isUntrustedShellLockdownActive } from "../../runtime/effective-capabilities.js";
 import { redactSecrets } from "../../security/secret-scanner.js";
 import { getLogger } from "../../util/logger.js";
 import { getDataDir } from "../../util/platform.js";
+import type { CompletedBackgroundTool } from "../background-tool-registry.js";
 import {
   generateBackgroundToolId,
   isBackgroundToolLimitReached,
   MAX_BACKGROUND_TOOLS,
+  recordCompletedBackgroundTool,
   registerBackgroundTool,
   removeBackgroundTool,
 } from "../background-tool-registry.js";
@@ -346,6 +350,7 @@ export const shellTool = {
       const stdoutChunks: Buffer[] = [];
       const stderrChunks: Buffer[] = [];
       let timedOut = false;
+      let aborted = false;
       const startedAt = Date.now();
 
       const child = spawn(wrapped.command, wrapped.args, {
@@ -409,20 +414,66 @@ export const shellTool = {
           timeoutSec,
         );
 
-        const framing = `Background command completed (id=${bgId}, exit=${code ?? "unknown"}):`;
+        const status: BackgroundToolCompleted["status"] = aborted
+          ? "cancelled"
+          : timedOut
+            ? "failed"
+            : code === 0
+              ? "completed"
+              : "failed";
+        // A cancelled command exits with a null code, which formatShellOutput
+        // frames as "failed"; surface the cancellation instead.
+        const output =
+          status === "cancelled"
+            ? `Background command cancelled (id=${bgId}).`
+            : fmtResult.content;
+        const completedAt = Date.now();
+        const completion: CompletedBackgroundTool = {
+          id: bgId,
+          toolName: "bash",
+          conversationId: context.conversationId,
+          command,
+          startedAt,
+          status,
+          exitCode: code ?? null,
+          output,
+          completedAt,
+        };
+
+        // Wake AFTER the terminal status is known so a user-cancelled run wakes
+        // the assistant with the cancellation — not the SIGKILL-framed "completed"
+        // output — matching the recorded/broadcast status and the inline card.
+        const framing =
+          status === "cancelled"
+            ? `Background command cancelled (id=${bgId}):`
+            : `Background command completed (id=${bgId}, exit=${code ?? "unknown"}):`;
         void wakeAgentForOpportunity({
           conversationId: context.conversationId,
           hint: framing,
           source: "background-tool",
           persistTriggerAsEvent: true,
+          backgroundToolCompletion: completion,
           untrustedOutput: {
-            content: fmtResult.content,
+            content: output,
             source: "tool_result",
             // Already bounded + recovery-marked by formatShellOutput; a larger
             // budget keeps wrapUntrustedContent from re-truncating the marker.
             maxChars: MAX_OUTPUT_LENGTH * 2,
           },
         });
+        recordCompletedBackgroundTool(completion);
+        broadcastMessage(
+          {
+            type: "background_tool_completed",
+            id: bgId,
+            conversationId: context.conversationId,
+            status,
+            exitCode: code ?? null,
+            output,
+            completedAt,
+          },
+          context.conversationId,
+        );
       });
 
       child.on("error", (err) => {
@@ -444,12 +495,40 @@ export const shellTool = {
           spawnError: err.message,
         });
 
+        const framing = `Background command failed (id=${bgId}): ${err.message}`;
+        const completedAt = Date.now();
+        const completion: CompletedBackgroundTool = {
+          id: bgId,
+          toolName: "bash",
+          conversationId: context.conversationId,
+          command,
+          startedAt,
+          status: "failed",
+          exitCode: null,
+          output: framing,
+          completedAt,
+        };
         void wakeAgentForOpportunity({
           conversationId: context.conversationId,
-          hint: `Background command failed (id=${bgId}): ${err.message}`,
+          hint: framing,
           source: "background-tool",
           persistTriggerAsEvent: true,
+          backgroundToolCompletion: completion,
         });
+
+        recordCompletedBackgroundTool(completion);
+        broadcastMessage(
+          {
+            type: "background_tool_completed",
+            id: bgId,
+            conversationId: context.conversationId,
+            status: "failed",
+            exitCode: null,
+            output: framing,
+            completedAt,
+          },
+          context.conversationId,
+        );
       });
 
       registerBackgroundTool({
@@ -458,9 +537,24 @@ export const shellTool = {
         conversationId: context.conversationId,
         command,
         startedAt,
-        cancel: () => killTree("abort"),
+        cancel: () => {
+          aborted = true;
+          killTree("abort");
+        },
       });
 
+      broadcastMessage(
+        {
+          type: "background_tool_started",
+          id: bgId,
+          toolName: "bash",
+          conversationId: context.conversationId,
+          command,
+          startedAt,
+        },
+        context.conversationId,
+      );
+
       return {
         content: JSON.stringify({ backgrounded: true, id: bgId }),
         isError: false,