@vellumai/assistant 0.8.5 → 0.8.7

package/src/runtime/routes/workspace-routes.ts

@@ -4,6 +4,7 @@
  * Do not store secrets here — use the credential store or protected/ directory.
  */
 import {
+  type Dirent,
   existsSync,
   mkdirSync,
   readdirSync,
@@ -18,6 +19,7 @@ import { basename, dirname, join } from "node:path";
 import { z } from "zod";
 
 import { getWorkspaceDir } from "../../util/platform.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { publishSoundsConfigUpdated } from "../sync/resource-sync-events.js";
 import {
   BadRequestError,
@@ -33,13 +35,77 @@ import {
   resolveWorkspacePath,
 } from "./workspace-utils.js";
 
-interface TreeEntry {
-  name: string;
-  path: string;
-  type: "file" | "directory";
-  size: number | null;
-  mimeType: string | null;
-  modifiedAt: string;
+const workspaceTreeEntrySchema = z.object({
+  name: z.string(),
+  path: z.string(),
+  type: z.enum(["file", "directory"]),
+  size: z.number().nullable(),
+  mimeType: z.string().nullable(),
+  modifiedAt: z.string(),
+});
+
+type TreeEntry = z.infer<typeof workspaceTreeEntrySchema>;
+
+// Total number of filesystem entries we're willing to traverse when computing
+// recursive directory sizes for a single tree listing. The budget is shared
+// across every directory in the response so a giant `repos/` checkout cannot
+// starve the request — once exhausted, remaining directories report `size:
+// null` (caller renders an unknown-size placeholder). 50k is generous for
+// typical workspaces (sounds, db, logs) while bailing fast on multi-repo
+// trees.
+const DIR_SIZE_TOTAL_ENTRY_BUDGET = 50_000;
+
+interface DirSizeBudget {
+  remaining: number;
+}
+
+/**
+ * Recursively sum the byte size of every regular file under `absPath`,
+ * sharing a single entry budget across all directories in the same listing.
+ *
+ * Returns:
+ * - the total size in bytes when the entire subtree was traversed within
+ *   budget
+ * - `null` if the shared budget was exhausted before completion (the caller
+ *   surfaces that as an unknown size in the UI)
+ *
+ * Symlinks are not followed. We rely on `withFileTypes` so we never `stat`
+ * directories purely to discover their type.
+ */
+function computeDirSize(absPath: string, budget: DirSizeBudget): number | null {
+  if (budget.remaining <= 0) return null;
+
+  let total = 0;
+  const stack: string[] = [absPath];
+
+  while (stack.length > 0) {
+    const dir = stack.pop()!;
+
+    let dirents: Dirent[];
+    try {
+      dirents = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of dirents) {
+      if (budget.remaining <= 0) return null;
+      budget.remaining -= 1;
+
+      if (entry.isDirectory()) {
+        stack.push(join(dir, entry.name));
+      } else if (entry.isFile()) {
+        try {
+          total += statSync(join(dir, entry.name)).size;
+        } catch {
+          // unreadable file — skip, do not abort the whole computation
+        }
+      }
+      // symlinks, sockets, fifos, etc. are intentionally ignored
+    }
+  }
+
+  return total;
 }
 
 const SOUNDS_WORKSPACE_PATH = "data/sounds";
@@ -75,6 +141,7 @@ function publishSoundsConfigUpdatedForPaths(
 function handleWorkspaceTree({ queryParams }: RouteHandlerArgs) {
   const requestedPath = queryParams?.path ?? "";
   const showHidden = queryParams?.showHidden === "true";
+  const includeDirSizes = queryParams?.includeDirSizes === "true";
   const resolved = resolveWorkspacePath(requestedPath, {
     allowHidden: showHidden,
   });
@@ -86,6 +153,12 @@ function handleWorkspaceTree({ queryParams }: RouteHandlerArgs) {
     const dirents = readdirSync(resolved, { withFileTypes: true });
     const workspaceDir = getWorkspaceDir();
 
+    // Shared budget across every directory in this listing. When opted out,
+    // we never construct one, so directories report `size: null` as before.
+    const dirSizeBudget: DirSizeBudget | undefined = includeDirSizes
+      ? { remaining: DIR_SIZE_TOTAL_ENTRY_BUDGET }
+      : undefined;
+
     const entries: TreeEntry[] = [];
     for (const entry of dirents) {
       if (!showHidden && entry.name.startsWith(".")) continue;
@@ -102,11 +175,14 @@ function handleWorkspaceTree({ queryParams }: RouteHandlerArgs) {
       const isDir = stats.isDirectory();
       const relativePath = fullPath.slice(workspaceDir.length + 1);
 
+      const dirSize =
+        isDir && dirSizeBudget ? computeDirSize(fullPath, dirSizeBudget) : null;
+
       entries.push({
         name: entry.name,
         path: relativePath,
         type: isDir ? "directory" : "file",
-        size: isDir ? null : stats.size,
+        size: isDir ? dirSize : stats.size,
         mimeType: isDir ? null : Bun.file(fullPath).type,
         modifiedAt: stats.mtime.toISOString(),
       });
@@ -416,6 +492,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "workspace_tree",
     endpoint: "workspace/tree",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "List workspace directory",
     description: "Return directory entries for a workspace path.",
     tags: ["workspace"],
@@ -428,10 +508,17 @@ export const ROUTES: RouteDefinition[] = [
         name: "showHidden",
         description: "Include dotfiles (true/false)",
       },
+      {
+        name: "includeDirSizes",
+        description:
+          "Compute recursive byte size for each directory entry (true/false). Budget-bounded — large subtrees may return size: null.",
+      },
     ],
     responseBody: z.object({
       path: z.string(),
-      entries: z.array(z.unknown()).describe("Directory entry objects"),
+      entries: z
+        .array(workspaceTreeEntrySchema)
+        .describe("Directory entry objects"),
     }),
     handler: handleWorkspaceTree,
   },
@@ -439,6 +526,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "workspace_file",
     endpoint: "workspace/file",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get workspace file metadata",
     description:
       "Return file metadata and inline text content (if small enough).",
@@ -468,6 +559,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "workspace_write",
     endpoint: "workspace/write",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Write workspace file",
     description: "Create or overwrite a file in the workspace.",
     tags: ["workspace"],
@@ -489,6 +584,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "workspace_mkdir",
     endpoint: "workspace/mkdir",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Create workspace directory",
     description: "Create directories recursively in the workspace.",
     tags: ["workspace"],
@@ -504,6 +603,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "workspace_rename",
     endpoint: "workspace/rename",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Rename workspace entry",
     description: "Rename or move a file or directory in the workspace.",
     tags: ["workspace"],
@@ -521,6 +624,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "workspace_delete",
     endpoint: "workspace/delete",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Delete workspace entry",
     description: "Delete a file or directory from the workspace.",
     tags: ["workspace"],
@@ -536,6 +643,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "workspace_file_content",
     endpoint: "workspace/file/content",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get workspace file content",
     description: "Return raw file bytes with HTTP range support.",
     tags: ["workspace"],

package/src/runtime/services/__tests__/analyze-conversation.test.ts

@@ -46,6 +46,7 @@ mock.module("../../../memory/conversation-crud.js", () => ({
   addMessage: mockAddMessage,
   findAnalysisConversationFor: mockFindAnalysisConversationFor,
   getConversationSource: mockGetConversationSource,
+  reserveMessage: mock(async () => ({ id: "msg-reserve" })),
 }));
 
 mock.module("../../../export/transcript-formatter.js", () => ({
@@ -80,6 +81,7 @@ const testHub = new AssistantEventHub();
 mock.module("../../assistant-event-hub.js", () => ({
   AssistantEventHub,
   assistantEventHub: testHub,
+  broadcastMessage: async () => {},
 }));
 
 import { analyzeConversation } from "../analyze-conversation.js";
@@ -165,7 +167,7 @@ describe("analyzeConversation", () => {
       "analysis-new",
       "user",
       expect.any(String),
-      { provenanceTrustClass: "unknown" },
+      { metadata: { provenanceTrustClass: "unknown" } },
     );
 
     // Sets trust context to unknown.
@@ -190,7 +192,6 @@ describe("analyzeConversation", () => {
     expect(currentConversation.runAgentLoop).toHaveBeenCalledWith(
       expect.any(String),
       "msg-1",
-      undefined,
       expect.objectContaining({
         isInteractive: false,
         isUserMessage: true,
@@ -285,7 +286,7 @@ describe("analyzeConversation", () => {
       "analysis-existing",
       "user",
       expect.any(String),
-      { provenanceTrustClass: "guardian" },
+      { metadata: { provenanceTrustClass: "guardian" } },
     );
   });
 
@@ -364,7 +365,6 @@ describe("analyzeConversation", () => {
     expect(currentConversation.runAgentLoop).toHaveBeenCalledWith(
       expect.any(String),
       "msg-1",
-      undefined,
       expect.objectContaining({ callSite: "analyzeConversation" }),
     );
   });

package/src/runtime/services/analyze-conversation.ts

@@ -35,10 +35,7 @@ import {
 } from "../../memory/conversation-crud.js";
 import { resolveConversationId } from "../../memory/conversation-key-store.js";
 import { getLogger } from "../../util/logger.js";
-import {
-  assistantEventHub,
-  broadcastMessage,
-} from "../assistant-event-hub.js";
+import { assistantEventHub, broadcastMessage } from "../assistant-event-hub.js";
 import {
   buildAutoAnalysisPrompt,
   neutralizeTranscriptSentinel,
@@ -218,7 +215,7 @@ export async function analyzeConversation(
     analysisConversationId,
     "user",
     JSON.stringify([{ type: "text", text: prompt }]),
-    { provenanceTrustClass: trustClass },
+    { metadata: { provenanceTrustClass: trustClass } },
   );
   const messageId = message.id;
 
@@ -258,7 +255,7 @@ export async function analyzeConversation(
   // routes the per-call provider config through `resolveCallSiteConfig`
   // against `llm.callSites.analyzeConversation`.
   analysisConversation
-    .runAgentLoop(prompt, messageId, undefined, {
+    .runAgentLoop(prompt, messageId, {
       isInteractive: false,
       isUserMessage: true,
       callSite: "analyzeConversation",

package/src/runtime/services/conversation-serializer.ts

@@ -9,6 +9,7 @@
 
 import { parseChannelId } from "../../channels/types.js";
 import { getConfig } from "../../config/loader.js";
+import { findConversation } from "../../daemon/conversation-store.js";
 import { normalizeConversationType } from "../../daemon/message-types/shared.js";
 import {
   type AttentionState,
@@ -162,9 +163,24 @@ export function serializeConversationSummary(params: {
     groupId: string | null;
   };
   parentCache: Map<string, ConversationRow | null>;
+  /**
+   * Whether the agent loop is currently mid-turn for this conversation.
+   * Sourced from the in-memory daemon `Conversation.isProcessing()` flag
+   * — callers resolve via `findConversation(id)?.isProcessing() ?? false`
+   * so cold (evicted / never-loaded) rows report `false`. Plumbed in
+   * rather than read here so the serializer stays a pure shape mapper
+   * with no daemon-store coupling.
+   */
+  isProcessing: boolean;
 }) {
-  const { conversation, binding, attentionState, displayMeta, parentCache } =
-    params;
+  const {
+    conversation,
+    binding,
+    attentionState,
+    displayMeta,
+    parentCache,
+    isProcessing,
+  } = params;
   const originChannel = parseChannelId(conversation.originChannel);
   const assistantAttention = buildAssistantAttention(attentionState);
   const forkParent = buildForkParent(conversation, parentCache);
@@ -205,6 +221,7 @@ export function serializeConversationSummary(params: {
     ...(conversation.inferenceProfile != null
       ? { inferenceProfile: conversation.inferenceProfile }
       : {}),
+    isProcessing,
   };
 }
 
@@ -232,6 +249,11 @@ export function buildConversationDetailResponse(
       attentionState: attentionStates.get(conversation.id),
       displayMeta: displayMeta.get(conversation.id),
       parentCache,
+      // Cold (evicted / never-loaded) rows aren't in the in-memory
+      // store, so `findConversation` returns `undefined` and they
+      // report `isProcessing: false` — by definition they aren't
+      // mid-turn since the agent loop only runs on resident convs.
+      isProcessing: findConversation(conversation.id)?.isProcessing() ?? false,
     }),
   };
 }

package/src/runtime/slack-dm-text-delivery.ts

@@ -0,0 +1,177 @@
+import type { ChannelId } from "../channels/types.js";
+import type { ServerMessage } from "../daemon/message-protocol.js";
+import { getLogger } from "../util/logger.js";
+import { deliverChannelReply } from "./gateway-client.js";
+
+const log = getLogger("runtime-http");
+
+const NO_RESPONSE_INLINE_RE = /<no_response\s*\/?>/gi;
+
+export function isSlackDeliveryCallbackUrl(replyCallbackUrl?: string): boolean {
+  if (!replyCallbackUrl) return false;
+  try {
+    return new URL(replyCallbackUrl).pathname.endsWith("/deliver/slack");
+  } catch {
+    return replyCallbackUrl.endsWith("/deliver/slack");
+  }
+}
+
+export function shouldDeliverSlackDmTextResponses(params: {
+  sourceChannel: ChannelId;
+  chatType?: string;
+  replyCallbackUrl?: string;
+}): boolean {
+  return (
+    params.sourceChannel === "slack" &&
+    params.chatType === "im" &&
+    isSlackDeliveryCallbackUrl(params.replyCallbackUrl)
+  );
+}
+
+export type SlackDmTextDeliveryController = {
+  observeEvent: (msg: ServerMessage) => void;
+  waitForPendingDeliveries: () => Promise<void>;
+  getFinalDeliveryResumeOptions: (
+    messageId: string | undefined,
+  ) => { startFromSegment: number; messageTs?: string } | undefined;
+};
+
+export function createSlackDmTextDeliveryController(params: {
+  sourceChannel: ChannelId;
+  chatType?: string;
+  replyCallbackUrl?: string;
+  chatId: string;
+  assistantId?: string;
+  deliveredTextResponseIndexes?: readonly number[];
+  onTextResponseDelivered?: (
+    responseIndex: number,
+    reason: "before_tool" | "message_complete",
+  ) => void;
+}): SlackDmTextDeliveryController | undefined {
+  const { replyCallbackUrl } = params;
+  if (!shouldDeliverSlackDmTextResponses(params) || !replyCallbackUrl) {
+    return undefined;
+  }
+
+  const deliveredTextResponseIndexes = new Set(
+    params.deliveredTextResponseIndexes ?? [],
+  );
+  const messageIdToResponseIndexes = new Map<string, number[]>();
+  const responseIndexToMessageTs = new Map<number, string>();
+  let textResponseIndex = 0;
+  let pendingText = "";
+  let currentMessageResponseIndexes: number[] = [];
+  let deliveryChain = Promise.resolve();
+
+  const associateCurrentMessageResponses = (
+    messageId: string | undefined,
+  ): void => {
+    if (!messageId || currentMessageResponseIndexes.length === 0) return;
+    const responseIndexes = messageIdToResponseIndexes.get(messageId) ?? [];
+    for (const responseIndex of currentMessageResponseIndexes) {
+      if (!responseIndexes.includes(responseIndex)) {
+        responseIndexes.push(responseIndex);
+      }
+    }
+    messageIdToResponseIndexes.set(messageId, responseIndexes);
+    currentMessageResponseIndexes = [];
+  };
+
+  const flushPendingText = (
+    reason: "before_tool" | "message_complete",
+  ): void => {
+    const text = pendingText;
+    pendingText = "";
+
+    const deliverableText = text.replace(NO_RESPONSE_INLINE_RE, "").trim();
+    if (deliverableText.length === 0) return;
+
+    textResponseIndex += 1;
+    const currentResponseIndex = textResponseIndex;
+    currentMessageResponseIndexes.push(currentResponseIndex);
+    if (deliveredTextResponseIndexes.has(currentResponseIndex)) return;
+
+    deliveryChain = deliveryChain
+      .catch(() => undefined)
+      .then(async () => {
+        let result: Awaited<ReturnType<typeof deliverChannelReply>>;
+        try {
+          result = await deliverChannelReply(replyCallbackUrl, {
+            chatId: params.chatId,
+            text: deliverableText,
+            assistantId: params.assistantId,
+            useBlocks: true,
+          });
+        } catch (err) {
+          log.warn(
+            { err, chatId: params.chatId },
+            "Failed to deliver intermediate Slack DM assistant text",
+          );
+          return;
+        }
+
+        if (result.ts) {
+          responseIndexToMessageTs.set(currentResponseIndex, result.ts);
+        }
+        deliveredTextResponseIndexes.add(currentResponseIndex);
+        try {
+          params.onTextResponseDelivered?.(currentResponseIndex, reason);
+        } catch (err) {
+          log.warn(
+            { err, chatId: params.chatId, responseIndex: currentResponseIndex },
+            "Failed to persist intermediate Slack DM assistant text progress",
+          );
+        }
+      });
+  };
+
+  return {
+    observeEvent(msg) {
+      if (msg.type === "assistant_text_delta") {
+        pendingText += msg.text;
+        return;
+      }
+
+      if (msg.type === "message_complete") {
+        flushPendingText("message_complete");
+        if (typeof msg.messageId === "string") {
+          associateCurrentMessageResponses(msg.messageId);
+        }
+        currentMessageResponseIndexes = [];
+        return;
+      }
+
+      if (msg.type === "tool_use_start") {
+        flushPendingText("before_tool");
+      }
+    },
+    waitForPendingDeliveries: () => deliveryChain,
+    getFinalDeliveryResumeOptions: (messageId) => {
+      if (typeof messageId !== "string") {
+        return undefined;
+      }
+      const responseIndexes = messageIdToResponseIndexes.get(messageId) ?? [];
+      let deliveredPrefixCount = 0;
+      for (const responseIndex of responseIndexes) {
+        if (!deliveredTextResponseIndexes.has(responseIndex)) break;
+        deliveredPrefixCount += 1;
+      }
+      if (deliveredPrefixCount === 0) return undefined;
+
+      const firstLiveResponseIndex = responseIndexes[0];
+      const allTextResponsesDelivered =
+        responseIndexes.length > 0 &&
+        responseIndexes.every((responseIndex) =>
+          deliveredTextResponseIndexes.has(responseIndex),
+        );
+      const messageTs =
+        allTextResponsesDelivered && firstLiveResponseIndex !== undefined
+          ? responseIndexToMessageTs.get(firstLiveResponseIndex)
+          : undefined;
+      return {
+        startFromSegment: deliveredPrefixCount,
+        ...(messageTs ? { messageTs } : {}),
+      };
+    },
+  };
+}

package/src/runtime/sync/resource-sync-events.ts

@@ -1,5 +1,5 @@
+import type { ConversationListInvalidatedReason } from "../../api/events/conversation-list-invalidated.js";
 import type { IdentityFields } from "../../daemon/handlers/identity.js";
-import type { ConversationListInvalidatedReason } from "../../daemon/message-types/conversations.js";
 import {
   conversationMessagesSyncTag,
   conversationMetadataSyncTag,
@@ -29,7 +29,17 @@ export function publishIdentityChanged(
     emoji: fields.emoji,
     home: fields.home,
   });
-  void publishSyncInvalidation([SYNC_TAGS.assistantIdentity], originClientId);
+  void publishSyncInvalidation(
+    [SYNC_TAGS.assistantIdentity, SYNC_TAGS.assistantIdentityIntro],
+    originClientId,
+  );
+}
+
+export function publishIdentityIntroChanged(originClientId?: string): void {
+  void publishSyncInvalidation(
+    [SYNC_TAGS.assistantIdentityIntro],
+    originClientId,
+  );
 }
 
 export function publishConfigChanged(originClientId?: string): void {
@@ -46,6 +56,10 @@ export function publishSchedulesChanged(originClientId?: string): void {
   void publishSyncInvalidation([SYNC_TAGS.assistantSchedules], originClientId);
 }
 
+export function publishAppsChanged(originClientId?: string): void {
+  void publishSyncInvalidation([SYNC_TAGS.appsList], originClientId);
+}
+
 /**
  * Reasons that change the *shape* of the conversation list — a row is
  * added, removed, or its position changes. These require web clients to
@@ -64,7 +78,7 @@ const SHAPE_CHANGING_REASONS: ReadonlySet<ConversationListInvalidatedReason> =
  *
  * Web consumes `sync_changed` (`conversationsList` for shape changes,
  * `conversation:<id>:metadata` for content changes) directly and patches
- * the cached list in place — see `useAssistantSyncStream` for the consumer
+ * the cached list in place — see `useConversationSync` for the consumer
  * side. macOS (`ConversationRestorer.swift`) still listens for the typed
  * broadcast.
  *

package/src/runtime/sync/sync-publisher.ts

@@ -1,6 +1,6 @@
-import type { SyncChangedMessage } from "../../daemon/message-types/sync.js";
 import {
   buildSyncChangedMessage,
+  type SyncChangedEvent,
   type SyncInvalidationTag,
 } from "../../daemon/message-types/sync.js";
 import { getLogger } from "../../util/logger.js";
@@ -11,7 +11,7 @@ const log = getLogger("sync-publisher");
 export async function publishSyncInvalidation(
   tags: SyncInvalidationTag[],
   originClientId?: string,
-): Promise<SyncChangedMessage> {
+): Promise<SyncChangedEvent> {
   const message = buildSyncChangedMessage(tags, originClientId);
   try {
     broadcastMessage(message);

package/src/runtime/tool-grant-request-helper.ts

@@ -147,6 +147,7 @@ export function createOrReuseToolGrantRequest(
     sourceEventName: "guardian.question",
     sourceChannel: sourceChannel as NotificationSourceChannel,
     sourceContextId: conversationId,
+    requiresConversation: true,
     attentionHints: {
       requiresAction: true,
       urgency: "high",

package/src/schedule/run-script.ts

@@ -6,8 +6,16 @@ const log = getLogger("run-script");
 
 /** Maximum combined stdout + stderr captured (bytes). */
 const MAX_OUTPUT_BYTES = 10_000;
-/** Default timeout for script execution (ms). */
-const DEFAULT_TIMEOUT_MS = 60_000;
+/** Default timeout for script execution (ms) when a schedule sets no override. */
+export const DEFAULT_TIMEOUT_MS = 60_000;
+/** Smallest script timeout override a caller may set (ms). */
+export const MIN_SCRIPT_TIMEOUT_MS = 1_000;
+/**
+ * Largest script timeout override a caller may set (ms). Capped so a wedged
+ * script cannot block the scheduler tick indefinitely; mirrors the talk-mode
+ * budget in scheduler.ts.
+ */
+export const MAX_SCRIPT_TIMEOUT_MS = 30 * 60 * 1000;
 
 export interface ScriptResult {
   exitCode: number;
@@ -75,7 +83,9 @@ export async function runScript(
     ]);
     const stdout = truncate(stdoutStr);
     const timeoutMsg = `Script timed out after ${timeoutMs}ms`;
-    const stderr = truncate(stderrStr ? `${timeoutMsg}\n${stderrStr}` : timeoutMsg);
+    const stderr = truncate(
+      stderrStr ? `${timeoutMsg}\n${stderrStr}` : timeoutMsg,
+    );
     log.info(
       { command, timedOut: true, stdoutLen: stdout.length },
       "Script timed out",
@@ -98,3 +108,18 @@ function truncate(text: string): string {
   if (text.length <= MAX_OUTPUT_BYTES) return text;
   return text.slice(0, MAX_OUTPUT_BYTES) + "\n... (truncated)";
 }
+
+/**
+ * Validate a caller-supplied script timeout override (ms). Returns an error
+ * message when the value is not a positive integer within the allowed bounds,
+ * or `null` when it is acceptable.
+ */
+export function validateScriptTimeoutMs(value: number): string | null {
+  if (!Number.isInteger(value)) {
+    return "timeout_ms must be an integer number of milliseconds";
+  }
+  if (value < MIN_SCRIPT_TIMEOUT_MS || value > MAX_SCRIPT_TIMEOUT_MS) {
+    return `timeout_ms must be between ${MIN_SCRIPT_TIMEOUT_MS} and ${MAX_SCRIPT_TIMEOUT_MS} (ms)`;
+  }
+  return null;
+}