@vellumai/assistant 0.8.6 → 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-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/types.ts

@@ -3,13 +3,14 @@ import type {
   DiffInfo,
   ExecutionTarget,
   ProxyApprovalCallback,
-  RiskLevel,
   SensitiveOutputBinding,
   ToolExecutionErrorEvent,
   ToolExecutionStartEvent,
   ToolPermissionDeniedEvent,
   ToolPermissionPromptEvent,
 } from "@vellumai/skill-host-contracts";
+import { RiskLevel } from "@vellumai/skill-host-contracts";
+import { z } from "zod";
 
 import type { InterfaceId } from "../channels/types.js";
 import type { CesClient } from "../credential-execution/client.js";
@@ -317,30 +318,84 @@ export interface ToolContext {
 }
 
 /**
- * Author-facing tool spec — re-exported from `@vellumai/plugin-api`.
- * Loaders fill documented defaults for omitted fields via `finalizeTool`
- * in `tool-defaults.ts`.
+ * Schema describing the shape of a {@link ToolDefinition}. All fields are
+ * optional — loaders fill documented defaults for omitted fields via
+ * `finalizeTool` in `tool-defaults.ts`. The IPC layer parses incoming
+ * skill tools against this same schema and re-finalizes them locally,
+ * so author shape and wire shape are one schema.
+ *
+ * `input_schema` is `z.custom<object>(...)` rather than
+ * `z.record(z.string(), z.unknown())` so that authors can assign a typed
+ * JSON-schema literal (`{ type: "object", properties: { ... } }`)
+ * without `as Record<...>` gymnastics. The custom check still rejects
+ * `null`, primitives, and arrays at runtime.
+ *
+ * `execute` is `z.custom<(input, context) => Promise<ToolExecutionResult>>()`
+ * for the same reason — the wire path drops closures (they can't cross
+ * IPC) and `finalizeTool` synthesizes a no-op error closure on arrival.
+ * The custom shape gives `ToolDefinition.execute` a fully-typed
+ * signature via `z.infer` without an overlay type.
+ *
+ * Result: `ToolDefinition = z.infer<typeof ToolDefinitionSchema>` —
+ * one declaration, both `input_schema` and `execute` typed correctly.
  */
-export interface ToolDefinition {
+export const ToolDefinitionSchema = z.object({
+  /**
+   * Name the model sees when calling this tool. Loaders default to the
+   * source file basename (e.g. `tools/read.ts` → `read`) when omitted,
+   * so the literal only needs to set this when overriding the
+   * file-derived name.
+   */
+  name: z.string().min(1).optional(),
   /** Human-readable description shown to the model in the tool catalog. */
-  description?: string;
-  /** Author-asserted risk band — low / medium / high. Drives default permission gating. */
-  defaultRiskLevel?: RiskLevel;
+  description: z.string().optional(),
   /** JSON schema describing the tool's input arguments. */
-  input_schema?: object;
+  input_schema: z
+    .custom<object>(
+      (val) => val !== null && typeof val === "object" && !Array.isArray(val),
+      { message: "input_schema must be a plain object" },
+    )
+    .optional(),
+  /** Author-asserted risk band — low / medium / high. Drives default permission gating. */
+  defaultRiskLevel: z.enum(RiskLevel).optional(),
+  /** Tool category used for Slack channel `allowedToolCategories` enforcement. */
+  category: z.string().min(1).optional(),
   /** Where the tool runs — sandbox (assistant container) or host (guardian device via proxy). Resolved by `resolveExecutionTarget` if omitted. */
-  executionTarget?: ExecutionTarget;
-  /** Implementation invoked when the model calls the tool. */
-  execute?: (
-    input: Record<string, unknown>,
-    context: ToolContext,
-  ) => Promise<ToolExecutionResult>;
-}
+  executionTarget: z.enum(["sandbox", "host"]).optional(),
+  /**
+   * Implementation invoked when the model calls the tool. Optional
+   * because some `ToolDefinition` instances are schema-only (e.g.
+   * {@link ../memory/graph/tools.graphRememberDefinition},
+   * {@link ../messaging/style-analyzer.storeStyleAnalysisTool},
+   * {@link ../memory/v2/sweep-job.SWEEP_TOOL}) — handed to providers as
+   * a function-calling schema without ever being registered for
+   * execution. Closures can't cross IPC, so the wire path drops this
+   * and `finalizeTool` synthesizes a no-op error closure on arrival.
+   * Tool sources use `satisfies ToolDefinition` (not `: ToolDefinition`)
+   * so the inferred export type preserves `execute` as required at
+   * call sites that statically import the literal.
+   */
+  execute: z
+    .custom<
+      (
+        input: Record<string, unknown>,
+        context: ToolContext,
+      ) => Promise<ToolExecutionResult>
+    >()
+    .optional(),
+});
+
+/**
+ * Author-facing tool spec — re-exported from `@vellumai/plugin-api`.
+ * Loaders fill documented defaults for omitted fields via `finalizeTool`
+ * in `tool-defaults.ts`. The type is a direct `z.infer` of
+ * {@link ToolDefinitionSchema} — both `input_schema` and `execute` are
+ * typed correctly by the schema itself, no overlay needed.
+ */
+export type ToolDefinition = z.infer<typeof ToolDefinitionSchema>;
 
 /** Tool after the loader has derived its name and filled defaults. */
-export type LoadedTool = Required<ToolDefinition> & {
-  name: string;
-};
+export type Tool = Required<ToolDefinition>;
 
 /** The kind of extension that owns a tool. Core tools have no owner. */
 export type OwnerKind = "skill" | "mcp" | "plugin";
@@ -355,7 +410,3 @@ export interface OwnerInfo {
   /** ID of the owning extension (skill id / plugin name / MCP server id). */
   id: string;
 }
-
-export interface Tool extends LoadedTool {
-  category: string;
-}