@vellumai/assistant 0.8.5 → 0.8.7

package/src/tools/terminal/shell.ts

@@ -27,8 +27,8 @@ import { registerTool } from "../registry.js";
 import { formatShellOutput } from "../shared/shell-output.js";
 import type {
   ProxyEnvVars,
-  Tool,
   ToolContext,
+  ToolDefinition,
   ToolExecutionResult,
 } from "../types.js";
 import { buildSanitizedEnv } from "./safe-env.js";
@@ -44,50 +44,50 @@ function buildCredentialRefTrace(
 
 const log = getLogger("shell-tool");
 
-class ShellTool implements Tool {
-  name = "bash";
-  description = "Execute a shell command on the local machine";
-  category = "terminal";
-  executionTarget = "sandbox" as const;
-  defaultRiskLevel = RiskLevel.Medium;
-
-  input_schema = {
-        type: "object",
-        properties: {
-          command: {
-            type: "string",
-            description: "The shell command to execute",
-          },
-          activity: {
-            type: "string",
-            description:
-              'Brief non-technical explanation of what this command does and why, shown to a non-technical user in the permission prompt. Avoid jargon and technical terms. Good: "to check if a required program is installed on your computer". Bad: "to check if gcloud CLI is installed". Good: "to download a helper program". Bad: "to run npm install".',
-          },
-          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".',
-          },
-          background: {
-            type: "boolean",
-            description:
-              "Run the command in the background. The tool returns immediately with a background tool ID. When the process exits, its output is delivered to the conversation as a wake.",
-          },
-        },
-        required: ["command", "activity"],
-      };
+export const shellTool = {
+  name: "bash",
+  description: "Execute a shell command on the local machine",
+  category: "terminal",
+  executionTarget: "sandbox",
+  defaultRiskLevel: RiskLevel.Medium,
+
+  input_schema: {
+    type: "object",
+    properties: {
+      command: {
+        type: "string",
+        description: "The shell command to execute",
+      },
+      activity: {
+        type: "string",
+        description:
+          'Brief non-technical explanation of what this command does and why, shown to a non-technical user in the permission prompt. Avoid jargon and technical terms. Good: "to check if a required program is installed on your computer". Bad: "to check if gcloud CLI is installed". Good: "to download a helper program". Bad: "to run npm install".',
+      },
+      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".',
+      },
+      background: {
+        type: "boolean",
+        description:
+          "Run the command in the background. The tool returns immediately with a background tool ID. When the process exits, its output is delivered to the conversation as a wake.",
+      },
+    },
+    required: ["command", "activity"],
+  },
 
   async execute(
     input: Record<string, unknown>,
@@ -337,6 +337,7 @@ class ShellTool implements Tool {
       const stdoutChunks: Buffer[] = [];
       const stderrChunks: Buffer[] = [];
       let timedOut = false;
+      const startedAt = Date.now();
 
       const child = spawn(wrapped.command, wrapped.args, {
         cwd: context.workingDir,
@@ -345,11 +346,17 @@ class ShellTool implements Tool {
         detached: true,
       });
 
-      const killTree = buildKillTree(child);
+      const killTree = buildKillTree(child, {
+        toolName: "bash",
+        conversationId: context.conversationId,
+        command,
+        startedAt,
+        invocationId: bgId,
+      });
 
       const timer = setTimeout(() => {
         timedOut = true;
-        killTree();
+        killTree("timeout");
       }, timeoutMs);
 
       child.stdout.on("data", (data: Buffer) => {
@@ -365,12 +372,24 @@ class ShellTool implements Tool {
       // Only the first handler to fire should wake the agent.
       let completed = false;
 
-      child.on("close", (code) => {
+      child.on("close", (code, signal) => {
         if (completed) return;
         completed = true;
         clearTimeout(timer);
         removeBackgroundTool(bgId);
 
+        logShellExit({
+          toolName: "bash",
+          mode: "background",
+          invocationId: bgId,
+          conversationId: context.conversationId,
+          command,
+          startedAt,
+          exitCode: code,
+          signal,
+          timedOut,
+        });
+
         const stdout = Buffer.concat(stdoutChunks).toString();
         const stderr = Buffer.concat(stderrChunks).toString();
         const fmtResult = formatShellOutput(
@@ -395,6 +414,19 @@ class ShellTool implements Tool {
         clearTimeout(timer);
         removeBackgroundTool(bgId);
 
+        logShellExit({
+          toolName: "bash",
+          mode: "background",
+          invocationId: bgId,
+          conversationId: context.conversationId,
+          command,
+          startedAt,
+          exitCode: null,
+          signal: null,
+          timedOut,
+          spawnError: err.message,
+        });
+
         const hint = `Background command failed (id=${bgId}): ${err.message}`;
         void wakeAgentForOpportunity({
           conversationId: context.conversationId,
@@ -408,8 +440,8 @@ class ShellTool implements Tool {
         toolName: "bash",
         conversationId: context.conversationId,
         command,
-        startedAt: Date.now(),
-        cancel: killTree,
+        startedAt,
+        cancel: () => killTree("abort"),
       });
 
       return {
@@ -425,6 +457,7 @@ class ShellTool implements Tool {
       const stdoutChunks: Buffer[] = [];
       const stderrChunks: Buffer[] = [];
       let timedOut = false;
+      const startedAt = Date.now();
 
       const child = spawn(wrapped.command, wrapped.args, {
         cwd: context.workingDir,
@@ -433,18 +466,23 @@ class ShellTool implements Tool {
         detached: true,
       });
 
-      const killTree = buildKillTree(child);
+      const killTree = buildKillTree(child, {
+        toolName: "bash",
+        conversationId: context.conversationId,
+        command,
+        startedAt,
+      });
 
       const timer = setTimeout(() => {
         timedOut = true;
-        killTree();
+        killTree("timeout");
       }, timeoutMs);
 
       // Cooperative cancellation via AbortSignal
-      const onAbort = () => killTree();
+      const onAbort = () => killTree("abort");
       if (context.signal) {
         if (context.signal.aborted) {
-          killTree();
+          killTree("abort");
         } else {
           context.signal.addEventListener("abort", onAbort, { once: true });
         }
@@ -460,10 +498,21 @@ class ShellTool implements Tool {
         context.onOutput?.(data.toString());
       });
 
-      child.on("close", (code) => {
+      child.on("close", (code, signal) => {
         clearTimeout(timer);
         context.signal?.removeEventListener("abort", onAbort);
 
+        logShellExit({
+          toolName: "bash",
+          mode: "foreground",
+          conversationId: context.conversationId,
+          command,
+          startedAt,
+          exitCode: code,
+          signal,
+          timedOut,
+        });
+
         const stdout = Buffer.concat(stdoutChunks).toString();
         const stderr = Buffer.concat(stderrChunks).toString();
         const fmtResult = formatShellOutput(
@@ -484,6 +533,19 @@ class ShellTool implements Tool {
       child.on("error", (err) => {
         clearTimeout(timer);
         context.signal?.removeEventListener("abort", onAbort);
+
+        logShellExit({
+          toolName: "bash",
+          mode: "foreground",
+          conversationId: context.conversationId,
+          command,
+          startedAt,
+          exitCode: null,
+          signal: null,
+          timedOut,
+          spawnError: err.message,
+        });
+
         resolve({
           content: `Error spawning command: ${err.message}${
             (err as NodeJS.ErrnoException).code === "ENOENT"
@@ -496,19 +558,87 @@ class ShellTool implements Tool {
     });
 
     return result;
-  }
+  },
+} satisfies ToolDefinition;
+
+/**
+ * Structured teardown log. Pairs with the `"Executing shell command"`
+ * start log: every shell invocation now produces a start/exit pair so
+ * orphan-leak post-mortems can correlate command + exitCode + signal +
+ * timedOut + duration without spelunking through prose hints. The
+ * `signal === "SIGKILL"` + `timedOut === true` combination is the
+ * fingerprint left by the timeout watcher SIGKILLing the process group
+ * — i.e. the moment that creates the orphans.
+ */
+function logShellExit(args: {
+  toolName: string;
+  mode: "foreground" | "background";
+  conversationId: string;
+  command: string;
+  startedAt: number;
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  timedOut: boolean;
+  invocationId?: string;
+  spawnError?: string;
+}): void {
+  log.info(
+    {
+      toolName: args.toolName,
+      mode: args.mode,
+      invocationId: args.invocationId,
+      conversationId: args.conversationId,
+      command: redactSecrets(args.command),
+      durationMs: Date.now() - args.startedAt,
+      exitCode: args.exitCode,
+      signal: args.signal,
+      timedOut: args.timedOut,
+      spawnError: args.spawnError,
+    },
+    "Shell command exited",
+  );
 }
 
 /**
  * Kill the entire process tree of a child process. Tries the process group
  * first (negative PID), then falls back to killing the direct child if the
  * PID is unavailable or the group kill fails.
+ *
+ * Emits a structured `warn` log on every invocation: this is the
+ * ground-truth event that creates orphaned subprocesses (the SIGKILL hits
+ * the entire group, so the immediate bash child has no chance to reap its
+ * grandchildren; under bun-as-PID-1 they accumulate as `<defunct>`).
+ * `reason` lets the next zombie report point at a specific call site (the
+ * timeout watcher in the foreground/background branches, or an abort).
  */
-function buildKillTree(child: ChildProcess): () => void {
-  return () => {
-    if (child.pid != null) {
+function buildKillTree(
+  child: ChildProcess,
+  context: {
+    toolName: string;
+    conversationId: string;
+    command: string;
+    startedAt: number;
+    /** Stable id for this invocation — bgId for background tools. */
+    invocationId?: string;
+  },
+): (reason: "timeout" | "abort" | "spawn_error") => void {
+  return (reason) => {
+    const groupPid = child.pid ?? null;
+    log.warn(
+      {
+        toolName: context.toolName,
+        conversationId: context.conversationId,
+        command: redactSecrets(context.command),
+        durationMs: Date.now() - context.startedAt,
+        reason,
+        groupPid,
+        invocationId: context.invocationId,
+      },
+      "Shell process group SIGKILL'd — orphans expected to reparent to PID 1",
+    );
+    if (groupPid != null) {
       try {
-        process.kill(-child.pid, "SIGKILL");
+        process.kill(-groupPid, "SIGKILL");
         return;
       } catch {
         // Process group may have already exited — fall through.
@@ -522,5 +652,4 @@ function buildKillTree(child: ChildProcess): () => void {
   };
 }
 
-export const shellTool: Tool = new ShellTool();
 registerTool(shellTool);

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

@@ -10,7 +10,7 @@ import { createOrReuseToolGrantRequest } from "../runtime/tool-grant-request-hel
 import { redactSecrets } from "../security/secret-scanner.js";
 import { computeToolApprovalDigest } from "../security/tool-approval-digest.js";
 import { getLogger } from "../util/logger.js";
-import { getAllTools, getTool } from "./registry.js";
+import { getAllTools, getTool, getToolOwner } from "./registry.js";
 import { isSideEffectTool } from "./side-effects.js";
 import { summarizeToolInput } from "./tool-input-summary.js";
 import {
@@ -340,8 +340,12 @@ export class ToolApprovalHandler {
     const tool = getTool(name);
     if (!tool) {
       const allowedToolNames = context.allowedToolNames;
+      // List every registered tool. Tools that need an external resolver
+      // (computer-use, ui-surface, etc.) now return a structured error
+      // from their `execute()` when no resolver is connected, rather than
+      // being filtered out here — listing them surfaces a clearer path
+      // than hiding their names entirely.
       const available = getAllTools()
-        .filter((t) => t.executionMode !== "proxy" || context.proxyToolResolver)
         .map((t) => t.name)
         .filter((n) => !allowedToolNames || allowedToolNames.has(n))
         .sort()
@@ -368,8 +372,10 @@ export class ToolApprovalHandler {
 
     // Gate tools not active for the current turn
     if (context.allowedToolNames && !context.allowedToolNames.has(name)) {
-      const loadHint = tool.ownerSkillId
-        ? `Load the "${tool.ownerSkillId}" skill that provides this tool first.`
+      const owner = getToolOwner(name);
+      const ownerSkillId = owner?.kind === "skill" ? owner.id : undefined;
+      const loadHint = ownerSkillId
+        ? `Load the "${ownerSkillId}" skill that provides this tool first.`
         : `Load the skill that provides this tool first.`;
       const msg = `Tool "${name}" is not currently active. ${loadHint}`;
       const durationMs = Date.now() - startTime;

package/src/tools/tool-defaults.ts

@@ -1,18 +1,18 @@
 /**
  * Single source of truth for the defaults applied when a `ToolDefinition`
  * omits one of the normally-required fields, plus the `finalizeTool`
- * helper that lifts a `ToolDefinition` into a `LoadedTool`.
+ * helper that lifts a `ToolDefinition` into a `Tool`.
  *
  * Plugins, external loaders, and any other registration boundary that
  * accepts loose `ToolDefinition` objects from authors must run them
  * through `finalizeTool` before handing the result to a `registerXxxTools`
  * call. The registry types make this a hard rule: every registered tool
- * is a `LoadedTool` (`Required<ToolDefinition> & { name }`).
+ * is a `Tool` (`Required<ToolDefinition>`).
  */
 
 import type {
-  LoadedTool,
   RiskLevel,
+  Tool,
   ToolDefinition,
   ToolExecutionResult,
 } from "./types.js";
@@ -31,6 +31,10 @@ import type {
  * - `executionTarget` defaults to `sandbox` — author-supplied tool code
  *   runs in the assistant container by default; opt in to `host` when
  *   the tool proxies work to the connected client.
+ * - `category` defaults to empty — Slack channel `allowedToolCategories`
+ *   policy denies uncategorized tools when a category allow-list is set,
+ *   which is the correct deny-by-default for tools the author didn't
+ *   explicitly bucket.
  *
  * `execute` has no constant default because the default closure needs to
  * close over the tool's name to produce a useful error message; see
@@ -45,23 +49,28 @@ export const TOOL_DEFAULTS = Object.freeze({
     additionalProperties: false,
   }) as object,
   executionTarget: "sandbox" as const,
+  category: "",
 });
 
 /**
- * Fill the four normally-required `ToolDefinition` fields with documented
+ * Fill the five normally-required `ToolDefinition` fields with documented
  * defaults when the author omitted them, attach the registration-time
- * `name`, and return a `LoadedTool` that is safe to hand to a
+ * `name` (preferring an explicit override on the literal over the
+ * file-derived default), and return a `Tool` that is safe to hand to a
  * `registerXxxTools` call.
  *
+ * `defaultName` is optional — when omitted, the tool's own `name` field
+ * is the source of truth and `""` is the last-ditch fallback. The
+ * empty-string fallback is fail-loud: `registerSkillTools` rejects any
+ * tool with an empty name with a clear "tool.name is required" error.
+ *
  * The default `execute` returns an error result so the model sees a clear
  * "this tool isn't wired up" signal at call time. The owning loader still
  * registers the tool cleanly — a broken individual tool must never block
  * the registration batch.
  */
-export function finalizeTool(
-  tool: ToolDefinition,
-  name: string,
-): LoadedTool {
+export function finalizeTool(tool: ToolDefinition, defaultName = ""): Tool {
+  const name = tool.name ?? defaultName;
   const description =
     typeof tool.description === "string"
       ? tool.description
@@ -82,6 +91,7 @@ export function finalizeTool(
           isError: true,
         });
   const executionTarget = tool.executionTarget ?? TOOL_DEFAULTS.executionTarget;
+  const category = tool.category ?? TOOL_DEFAULTS.category;
   return {
     ...tool,
     name,
@@ -90,5 +100,6 @@ export function finalizeTool(
     input_schema,
     executionTarget,
     execute,
+    category,
   };
 }

package/src/tools/tool-manifest.ts

@@ -28,7 +28,7 @@ import { skillLoadTool } from "./skills/load.js";
 import { notifyParentTool } from "./subagent/notify-parent.js";
 import { requestSystemPermissionTool } from "./system/request-permission.js";
 import { shellTool } from "./terminal/shell.js";
-import type { Tool } from "./types.js";
+import type { ToolDefinition } from "./types.js";
 
 // ── Eager side-effect modules ───────────────────────────────────────
 // These static imports trigger top-level `registerTool()` side effects on
@@ -73,7 +73,7 @@ export const eagerModuleToolNames: string[] = [
 // This includes both previously-eager tools (referenced here so they survive
 // a test registry reset) and tools that have always been explicit.
 
-export const explicitTools: Tool[] = [
+export const explicitTools: ToolDefinition[] = [
   // Previously-eager tools - kept here so initializeTools() can re-register
   // them after __resetRegistryForTesting() clears the registry (ESM caching
   // prevents their side-effect registrations from re-running).
@@ -108,7 +108,7 @@ export const explicitTools: Tool[] = [
 // initializeTools() in registry.ts can conditionally include them.
 
 /** All CES tools - stable references for the manifest snapshot. */
-export const cesTools: Tool[] = [
+export const cesTools: ToolDefinition[] = [
   makeAuthenticatedRequestTool,
   runAuthenticatedCommandTool,
   manageSecureCommandTool,
@@ -119,7 +119,7 @@ export const cesTools: Tool[] = [
  * Returns an empty array when the flag is disabled so callers can
  * unconditionally iterate the result.
  */
-export function getCesToolsIfEnabled(): Tool[] {
+export function getCesToolsIfEnabled(): ToolDefinition[] {
   try {
     const config = getConfig();
     if (isCesToolsEnabled(config)) {

package/src/tools/tool-name-aliases.ts

@@ -1,19 +1,77 @@
-const TOOL_NAME_ALIASES = new Map<string, string>([
-  ["create_app", "app_create"],
+type ToolInputNormalizer = (
+  input: Record<string, unknown>,
+) => Record<string, unknown>;
+
+const TOOL_NAME_ALIASES = new Map<
+  string,
+  { canonicalName: string; normalizeInput?: ToolInputNormalizer }
+>([
+  ["create_app", { canonicalName: "app_create" }],
+  [
+    "computer_use_press_key",
+    {
+      canonicalName: "computer_use_key",
+      normalizeInput: normalizeLegacyComputerUsePressKeyInput,
+    },
+  ],
 ]);
 
-/**
- * Resolve high-confidence compatibility aliases before active-tool gating.
- * Keep this list narrow: aliases should only cover observed model drift where
- * the canonical target is active for the turn.
- */
-export function resolveToolNameAlias(
+export function resolveToolInvocationAlias(
   name: string,
+  input: Record<string, unknown>,
   allowedToolNames?: ReadonlySet<string>,
-): string {
-  if (allowedToolNames?.has(name)) return name;
-  const canonical = TOOL_NAME_ALIASES.get(name);
-  if (!canonical) return name;
-  if (allowedToolNames && !allowedToolNames.has(canonical)) return name;
-  return canonical;
+): { name: string; input: Record<string, unknown> } {
+  if (allowedToolNames?.has(name)) return { name, input };
+  const alias = TOOL_NAME_ALIASES.get(name);
+  if (!alias) return { name, input };
+  if (allowedToolNames && !allowedToolNames.has(alias.canonicalName)) {
+    return { name, input };
+  }
+  return {
+    name: alias.canonicalName,
+    input: alias.normalizeInput ? alias.normalizeInput(input) : input,
+  };
+}
+
+function normalizeLegacyComputerUsePressKeyInput(
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  const normalized = { ...input };
+  const key = typeof normalized.key === "string" ? normalized.key.trim() : "";
+  const modifiers = Array.isArray(normalized.modifiers)
+    ? normalized.modifiers.flatMap((modifier) => {
+        if (typeof modifier !== "string") return [];
+        const normalizedModifier = normalizeKeyModifier(modifier);
+        return normalizedModifier ? [normalizedModifier] : [];
+      })
+    : [];
+
+  delete normalized.modifiers;
+
+  if (key && modifiers.length > 0 && !key.includes("+")) {
+    normalized.key = [...new Set(modifiers), key.toLowerCase()].join("+");
+  } else if (key && !key.includes("+")) {
+    normalized.key = key.toLowerCase();
+  }
+
+  return normalized;
+}
+
+function normalizeKeyModifier(modifier: string): string | undefined {
+  switch (modifier.trim().toLowerCase()) {
+    case "cmd":
+    case "command":
+    case "meta":
+      return "cmd";
+    case "ctrl":
+    case "control":
+      return "ctrl";
+    case "option":
+    case "alt":
+      return "option";
+    case "shift":
+      return "shift";
+    default:
+      return undefined;
+  }
 }