@vellumai/assistant 0.10.0-dev.202606200318.c052d10 → 0.10.0-dev.202606201453.1417592

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.0-dev.202606200318.c052d10",
+  "version": "0.10.0-dev.202606201453.1417592",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/agent-loop-callsite-precedence.test.ts

@@ -9,8 +9,7 @@
  * for these knobs is silently ignored.
  *
  * Precedence (highest wins):
- *   1. Per-turn explicit (from `resolveSystemPrompt`'s
- *      `resolved.maxTokens` / `resolved.model`)
+ *   1. Per-run explicit (from `run()`'s `model` param)
  *   2. Call-site resolved values (from `resolveCallSiteConfig` via the
  *      normalizer)
  *   3. Conversation defaults (`this.config.*`, from `llm.default`)
@@ -33,7 +32,6 @@ mock.module("../config/loader.js", () => ({
   getConfig: () => ({ llm: mockLlmConfig }),
 }));
 
-import type { ResolvedSystemPrompt } from "../agent/loop.js";
 import { AgentLoop } from "../agent/loop.js";
 import { LLMSchema } from "../config/schemas/llm.js";
 import { RetryProvider } from "../providers/retry.js";
@@ -298,41 +296,4 @@ describe("AgentLoop — call-site precedence", () => {
     // No callSite → loop sets the wire-format thinking directly.
     expect(config.thinking).toEqual({ type: "adaptive" });
   });
-
-  test("per-turn resolveSystemPrompt.maxTokens wins over both call-site and default", async () => {
-    setLlmConfig({
-      default: {
-        provider: "anthropic",
-        model: "claude-default",
-        maxTokens: 64000,
-      },
-      callSites: { mainAgent: { maxTokens: 4096 } },
-    });
-
-    const { provider, lastConfig } = makePipeline("anthropic");
-    const resolveSystemPrompt = (): ResolvedSystemPrompt => ({
-      systemPrompt: "per-turn system",
-      maxTokens: 8192,
-    });
-
-    const loop = new AgentLoop({
-      provider: provider,
-      systemPrompt: "system",
-      conversationId: "test-conversation",
-      config: { maxTokens: 64000 },
-      resolveSystemPrompt: resolveSystemPrompt,
-    });
-
-    await loop.run({
-      requestId: "test-request",
-      messages: [userMessage],
-      onEvent: () => {},
-      trust: { sourceChannel: "vellum", trustClass: "unknown" },
-      callSite: "mainAgent",
-    });
-
-    // Per-turn explicit value beats both the call-site (4096) and the
-    // default (64000).
-    expect(lastConfig()!.max_tokens).toBe(8192);
-  });
 });

package/src/__tests__/agent-wake-override-profile.test.ts

@@ -103,6 +103,8 @@ function makeTarget(): {
     drainQueue: async () => {},
     // Pre-run auto-compaction gate — no-op for these tests.
     maybeCompact: async () => null,
+    buildCurrentSystemPrompt: () => "mock-system-prompt",
+    modelOverride: undefined,
   };
   return { target: target as unknown as Conversation, runArgs };
 }

package/src/__tests__/app-source-watcher.test.ts

@@ -3,14 +3,7 @@
  * file changes and triggers debounced recompile + surface refresh.
  */
 
-import {
-  afterEach,
-  beforeEach,
-  describe,
-  expect,
-  mock,
-  test,
-} from "bun:test";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
 // ---------------------------------------------------------------------------
 // Mocks — must be set up before importing the module under test
@@ -19,8 +12,16 @@ import {
 const TEST_APPS_DIR = "/tmp/test-apps";
 const testDirNameMap = new Map<string, string>([["my-app", "app-id-1"]]);
 
-let capturedWatchCallback: ((eventType: string, filename: string | null) => void) | null = null;
-const mockWatcher = { close: mock(() => {}) };
+let capturedWatchCallback:
+  | ((eventType: string, filename: string | null) => void)
+  | null = null;
+let capturedErrorHandler: ((err: unknown) => void) | null = null;
+const mockWatcher = {
+  close: mock(() => {}),
+  on: mock((event: string, handler: (err: unknown) => void) => {
+    if (event === "error") capturedErrorHandler = handler;
+  }),
+};
 const mockExistsSync = mock((p: string): boolean => p === TEST_APPS_DIR);
 const mockWatch = mock(
   (
@@ -68,7 +69,9 @@ describe("AppSourceWatcher", () => {
     watcher = new AppSourceWatcher();
     onChangeSpy = mock(() => {});
     capturedWatchCallback = null;
+    capturedErrorHandler = null;
     mockWatcher.close.mockClear();
+    mockWatcher.on.mockClear();
     // Reset existsSync to default behavior for each test
     mockExistsSync.mockImplementation((p: string) => p === TEST_APPS_DIR);
   });
@@ -182,4 +185,21 @@ describe("AppSourceWatcher", () => {
     watcher.ensureStarted();
     expect(mockWatch.mock.calls.length).toBe(callCountAfterStart); // no extra watch call
   });
+
+  /**
+   * REGRESSION: a recursive watch over a large app tree (node_modules) can
+   * exhaust the inotify watch limit and emit ENOSPC asynchronously as an
+   * 'error' event. Without an 'error' listener that rethrows as an
+   * uncaughtException and crashes the daemon. The watcher must swallow it.
+   */
+  test("attaches an 'error' handler that does not rethrow on async ENOSPC", () => {
+    watcher.start(onChangeSpy);
+
+    expect(capturedErrorHandler).not.toBeNull();
+    const enospc = Object.assign(
+      new Error("ENOSPC: no space left on device, watch"),
+      { code: "ENOSPC", errno: -28, syscall: "watch" },
+    );
+    expect(() => capturedErrorHandler!(enospc)).not.toThrow();
+  });
 });

package/src/__tests__/config-schema.test.ts

@@ -122,6 +122,8 @@ describe("AssistantConfigSchema", () => {
       permissionTimeoutSec: 300,
       toolExecutionTimeoutSec: 120,
       providerStreamTimeoutSec: 1800,
+      backgroundTurnTimeoutSec: 1800,
+      scheduleTurnTimeoutSec: 1800,
     });
     expect(result.rateLimit).toEqual({
       maxRequestsPerMinute: 0,
@@ -666,6 +668,38 @@ describe("AssistantConfigSchema", () => {
     expect(result.timeouts.permissionTimeoutSec).toBe(300);
   });
 
+  test("background/schedule turn timeouts default to 1800s when unset", () => {
+    const result = AssistantConfigSchema.parse({
+      timeouts: { shellDefaultTimeoutSec: 30 },
+    });
+    expect(result.timeouts.backgroundTurnTimeoutSec).toBe(1800);
+    expect(result.timeouts.scheduleTurnTimeoutSec).toBe(1800);
+  });
+
+  test("custom background/schedule turn timeouts flow through to resolved config", () => {
+    const result = AssistantConfigSchema.parse({
+      timeouts: {
+        backgroundTurnTimeoutSec: 3600,
+        scheduleTurnTimeoutSec: 10800,
+      },
+    });
+    expect(result.timeouts.backgroundTurnTimeoutSec).toBe(3600);
+    expect(result.timeouts.scheduleTurnTimeoutSec).toBe(10800);
+  });
+
+  test("rejects non-integer and out-of-range turn timeouts", () => {
+    expect(
+      AssistantConfigSchema.safeParse({
+        timeouts: { backgroundTurnTimeoutSec: 12.5 },
+      }).success,
+    ).toBe(false);
+    expect(
+      AssistantConfigSchema.safeParse({
+        timeouts: { scheduleTurnTimeoutSec: 2147484 },
+      }).success,
+    ).toBe(false);
+  });
+
   test("accepts zero for non-negative fields", () => {
     const result = AssistantConfigSchema.parse({
       rateLimit: { maxRequestsPerMinute: 0 },

package/src/__tests__/conversation-agent-loop-disk-pressure.test.ts

@@ -178,6 +178,9 @@ function makeCtx(overrides: Partial<Context> = {}): Conversation {
     drainQueue: async () => {},
     getTurnInterfaceContext: () => null,
     getTurnChannelContext: () => null,
+
+    buildCurrentSystemPrompt: () => "system prompt",
+    modelOverride: undefined,
     graphMemory: {} as Context["graphMemory"],
     ...overrides,
   } as unknown as Conversation;

package/src/__tests__/conversation-agent-loop-inference-profile.test.ts

@@ -507,6 +507,9 @@ function makeCtx(
       assistantMessageChannel: "vellum" as const,
     }),
 
+    buildCurrentSystemPrompt: () => "system prompt",
+    modelOverride: undefined,
+
     graphMemory: {
       onCompacted: async () => {},
       prepareMemory: async () => ({

package/src/__tests__/conversation-agent-loop-overflow.test.ts

@@ -651,6 +651,9 @@ function makeCtx(
       assistantMessageChannel: "vellum" as const,
     }),
 
+    buildCurrentSystemPrompt: () => "system prompt",
+    modelOverride: undefined,
+
     graphMemory: {
       onCompacted: async () => {},
       prepareMemory: async () => ({

package/src/__tests__/conversation-agent-loop.test.ts

@@ -759,6 +759,9 @@ function makeCtx(
       assistantMessageChannel: "vellum" as const,
     }),
 
+    buildCurrentSystemPrompt: () => "system prompt",
+    modelOverride: undefined,
+
     graphMemory: {
       onCompacted: async () => {},
       prepareMemory: async () => ({

package/src/__tests__/conversation-process-callsite.test.ts

@@ -20,15 +20,11 @@ import type { Message, ProviderResponse } from "../providers/types.js";
 const captured: {
   callSite?: string;
   constructorMaxTokens?: unknown;
-  resolvedMaxTokens?: unknown;
-  resolvedHasMaxTokens?: boolean;
 } = {};
 
 function clearCaptured(): void {
   captured.callSite = undefined;
   captured.constructorMaxTokens = undefined;
-  captured.resolvedMaxTokens = undefined;
-  captured.resolvedHasMaxTokens = undefined;
 }
 
 mock.module("../util/logger.js", () => ({
@@ -207,14 +203,8 @@ mock.module("../agent/loop.js", () => ({
       provider?: unknown;
       systemPrompt?: string;
       config?: Record<string, unknown>;
-      resolveSystemPrompt?: (history: Message[]) => Record<string, unknown>;
     }) {
       captured.constructorMaxTokens = options?.config?.maxTokens;
-      const resolved = options?.resolveSystemPrompt?.([]);
-      captured.resolvedMaxTokens = resolved?.maxTokens;
-      captured.resolvedHasMaxTokens =
-        resolved !== undefined &&
-        Object.prototype.hasOwnProperty.call(resolved, "maxTokens");
     }
     getToolTokenBudget() {
       return 0;
@@ -381,8 +371,6 @@ describe("processMessage callSite threading", () => {
     await getOrCreateConversation("conv-store-default");
 
     expect(captured.constructorMaxTokens).toBeUndefined();
-    expect(captured.resolvedMaxTokens).toBeUndefined();
-    expect(captured.resolvedHasMaxTokens).toBe(false);
   });
 
   test("preserves explicit maxResponseTokens at conversation creation", async () => {
@@ -403,8 +391,6 @@ describe("processMessage callSite threading", () => {
     });
 
     expect(captured.constructorMaxTokens).toBe(1234);
-    expect(captured.resolvedMaxTokens).toBe(1234);
-    expect(captured.resolvedHasMaxTokens).toBe(true);
   });
 
   test("applies clientTimezone in the create and reuse transport metadata path", async () => {

package/src/__tests__/db-llm-request-log-provider-migration.test.ts

@@ -25,6 +25,7 @@ import { getSqliteFrom } from "../memory/db-connection.js";
 import { initializeDb } from "../memory/db-init.js";
 import { migrateLlmRequestLogProvider } from "../memory/migrations/184-llm-request-log-provider.js";
 import * as schema from "../memory/schema.js";
+import { getLogsDbPath } from "../util/logs-db-path.js";
 import { getDbPath } from "../util/platform.js";
 import { resetDbForTesting } from "./db-test-helpers.js";
 
@@ -62,11 +63,13 @@ describe("llm_request_logs provider migration", () => {
     process.env.BUN_TEST = "0";
     resetDbForTesting();
     removeTestDbFiles(getDbPath());
+    removeTestDbFiles(getLogsDbPath());
   });
 
   afterEach(() => {
     resetDbForTesting();
     removeTestDbFiles(getDbPath());
+    removeTestDbFiles(getLogsDbPath());
   });
 
   afterAll(() => {
@@ -77,12 +80,14 @@ describe("llm_request_logs provider migration", () => {
     }
     resetDbForTesting();
     removeTestDbFiles(getDbPath());
+    removeTestDbFiles(getLogsDbPath());
   });
 
   test("fresh DB initialization includes llm_request_logs.provider", () => {
     initializeDb();
 
-    const raw = new Database(getDbPath());
+    // llm_request_logs now lives in the attached logs database.
+    const raw = new Database(getLogsDbPath());
     const columns = getColumnInfo(raw);
 
     expect(columns.some((column) => column.name === "provider")).toBe(true);

package/src/__tests__/heartbeat-disk-pressure.test.ts

@@ -26,6 +26,9 @@ mock.module("../config/loader.js", () => ({
       activeHoursStart: undefined,
       activeHoursEnd: undefined,
     },
+    timeouts: {
+      backgroundTurnTimeoutSec: 1800,
+    },
   }),
   loadConfig: () => ({}),
   loadRawConfig: () => ({}),

package/src/__tests__/heartbeat-service.test.ts

@@ -47,6 +47,9 @@ let mockConfig = {
     activeHoursEnd: undefined as number | undefined,
     disposition: "Default disposition text mentioning notifications skill.",
   },
+  timeouts: {
+    backgroundTurnTimeoutSec: 1800,
+  },
 };
 
 mock.module("../config/loader.js", () => ({
@@ -399,6 +402,9 @@ describe("HeartbeatService", () => {
         activeHoursEnd: undefined,
         disposition: "Default disposition text mentioning notifications skill.",
       },
+      timeouts: {
+        backgroundTurnTimeoutSec: 1800,
+      },
     };
   });
 

package/src/__tests__/list-messages-attachments.test.ts

@@ -164,6 +164,47 @@ describe("handleListMessages attachments", () => {
     expect(imgAtt!.data).toBe(IMAGE_BASE64);
     expect(docAtt!.data).toBeUndefined();
   });
+
+  test("attachment-only assistant message synthesizes contentBlocks", async () => {
+    // When the assistant's entire response was a <vellum-attachment/> tag,
+    // parseDirectives strips it → cleanText is empty → renderHistoryContent
+    // drops the empty text block → contentBlocks is []. The serializer must
+    // synthesize attachment blocks from msgAttachments so the client has a
+    // block to anchor the attachment chip.
+    const conv = createConversation();
+    // Persist the post-strip content: an empty text block (what
+    // cleanAssistantContent leaves after stripping the directive tag).
+    const msg = await addMessage(
+      conv.id,
+      "assistant",
+      JSON.stringify([{ type: "text", text: "" }]),
+    );
+    const stored = uploadAttachment("output.png", "image/png", IMAGE_BASE64);
+    linkAttachmentToMessage(msg.id, stored.id, 0);
+
+    const response = handleListMessages(createTestArgs(conv.id));
+    const body = response as {
+      messages: {
+        attachments?: AttachmentPayload[];
+        contentBlocks?: Array<{
+          type: string;
+          attachment?: { id: string; filename: string };
+        }>;
+      }[];
+    };
+
+    expect(body.messages).toHaveLength(1);
+    // Attachments are always on the wire
+    expect(body.messages[0].attachments).toBeDefined();
+    expect(body.messages[0].attachments).toHaveLength(1);
+    // contentBlocks must be synthesized — not omitted
+    expect(body.messages[0].contentBlocks).toBeDefined();
+    expect(body.messages[0].contentBlocks).toHaveLength(1);
+    expect(body.messages[0].contentBlocks![0].type).toBe("attachment");
+    expect(body.messages[0].contentBlocks![0].attachment!.filename).toBe(
+      "output.png",
+    );
+  });
 });
 
 describe("handleListMessages no_response filtering", () => {

package/src/__tests__/plugin-source-watcher.test.ts

@@ -19,7 +19,13 @@ let capturedWatchCallback:
   | ((eventType: string, filename: string | null) => void)
   | null = null;
 let mockWatchShouldThrow = false;
-const mockWatcher = { close: mock(() => {}) };
+let capturedErrorHandler: ((err: unknown) => void) | null = null;
+const mockWatcher = {
+  close: mock(() => {}),
+  on: mock((event: string, handler: (err: unknown) => void) => {
+    if (event === "error") capturedErrorHandler = handler;
+  }),
+};
 
 const mockWatch = mock(
   (
@@ -90,8 +96,10 @@ describe("PluginSourceWatcher", () => {
   beforeEach(() => {
     PluginSourceWatcher.resetForTests();
     capturedWatchCallback = null;
+    capturedErrorHandler = null;
     mockWatchShouldThrow = false;
     mockWatcher.close.mockClear();
+    mockWatcher.on.mockClear();
     mockWatch.mockClear();
     mockRereadirSync.mockClear();
     mockGetRegisteredPlugin.mockClear();
@@ -240,6 +248,30 @@ describe("PluginSourceWatcher", () => {
     expect(capturedWatchCallback).toBe(firstCallback);
   });
 
+  /**
+   * REGRESSION: a recursive watch over a large plugin tree (node_modules)
+   * can exhaust the inotify watch limit and emit ENOSPC asynchronously as an
+   * 'error' event. An FSWatcher with no 'error' listener rethrows, which
+   * becomes an uncaughtException and crashes the daemon (CrashLoopBackOff).
+   * The watcher must register an 'error' handler that swallows it.
+   */
+  test("attaches an 'error' handler that does not rethrow on async ENOSPC", () => {
+    const watcher = PluginSourceWatcher.getInstance();
+    watcher.start();
+
+    expect(capturedErrorHandler).not.toBeNull();
+    const enospc = Object.assign(
+      new Error("ENOSPC: no space left on device, watch"),
+      {
+        code: "ENOSPC",
+        errno: -28,
+        syscall: "watch",
+      },
+    );
+    // Must not throw — the daemon stays up, the watcher just stops delivering.
+    expect(() => capturedErrorHandler!(enospc)).not.toThrow();
+  });
+
   test("singleton instance is shared across calls", () => {
     const watcher1 = PluginSourceWatcher.getInstance();
     const watcher2 = PluginSourceWatcher.getInstance();

package/src/__tests__/usage-cache-backfill-migration.test.ts

@@ -96,9 +96,13 @@ function insertRequestLog(args: {
   createdAt: number;
   responsePayload: string;
 }): void {
+  // Migration 140 runs before the table is relocated to the logs database (297
+  // runs last), so it reads llm_request_logs from `main`. Seed there to mirror
+  // that ordering — the unqualified reads in the migration resolve to `main`
+  // when a same-named table is present there.
   rawRun(
     /*sql*/ `
-    INSERT INTO llm_request_logs (
+    INSERT INTO main.llm_request_logs (
       id,
       conversation_id,
       request_payload,
@@ -144,7 +148,18 @@ function foreignResponsePayload(): string {
 
 describe("migrateBackfillUsageCacheAccounting", () => {
   beforeEach(() => {
-    getSqlite().run(`DELETE FROM llm_request_logs`);
+    // Recreate the pre-relocation `main.llm_request_logs` that migration 140
+    // reads (the live DB keeps the table in the attached logs database).
+    getSqlite().exec(`
+      CREATE TABLE IF NOT EXISTS main.llm_request_logs (
+        id TEXT PRIMARY KEY,
+        conversation_id TEXT NOT NULL,
+        request_payload TEXT NOT NULL,
+        response_payload TEXT NOT NULL,
+        created_at INTEGER NOT NULL
+      )
+    `);
+    getSqlite().run(`DELETE FROM main.llm_request_logs`);
     getSqlite().run(`DELETE FROM llm_usage_events`);
     rawRun(`DELETE FROM memory_checkpoints WHERE key = ?`, CHECKPOINT_KEY);
     mockPricingOverrides = [];

package/src/acp/__tests__/session-manager.test.ts

@@ -8,6 +8,10 @@ import { describe, expect, mock, test } from "bun:test";
 
 import type { AcpSessionState } from "../types.js";
 
+// Records every `cancel(protocolSessionId)` the manager dispatches to a fake
+// process, so tests can assert which sessions were cancelled.
+const cancelCalls: string[] = [];
+
 // Stub the agent-process module so spawn() does not actually launch a child
 // process. Each fake instance records the cwd it was spawned in and resolves
 // every protocol method synchronously. The mock is process-global (Bun's
@@ -30,7 +34,9 @@ mock.module("../agent-process.js", () => ({
       // the duration of the test so cleanup logic doesn't tear it down.
       return new Promise(() => {});
     }
-    async cancel(): Promise<void> {}
+    async cancel(sessionId: string): Promise<void> {
+      cancelCalls.push(sessionId);
+    }
     kill(): void {}
   },
 }));
@@ -81,3 +87,68 @@ describe("AcpSessionManager — parentConversationId population", () => {
     expect(parents).toEqual(["conv-parent-1", "conv-parent-2"]);
   });
 });
+
+describe("AcpSessionManager — cancelForParent", () => {
+  const noopSend = () => {};
+
+  test("cancels only the sessions spawned by the given parent", async () => {
+    cancelCalls.length = 0;
+    const manager = new AcpSessionManager(5);
+
+    const a1 = await manager.spawn(
+      "agent-a1",
+      { command: "echo", args: ["hi"] },
+      "task",
+      "/tmp",
+      "parent-A",
+      noopSend,
+    );
+    const a2 = await manager.spawn(
+      "agent-a2",
+      { command: "echo", args: ["hi"] },
+      "task",
+      "/tmp",
+      "parent-A",
+      noopSend,
+    );
+    const b1 = await manager.spawn(
+      "agent-b1",
+      { command: "echo", args: ["hi"] },
+      "task",
+      "/tmp",
+      "parent-B",
+      noopSend,
+    );
+
+    // WHEN parent-A is cancelled
+    const count = manager.cancelForParent("parent-A");
+
+    // THEN it reports the two parent-A sessions and leaves parent-B alone
+    expect(count).toBe(2);
+
+    // Let the detached per-session cancels settle (each awaits a protocol
+    // notification before flipping status).
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect((manager.getStatus(a1.acpSessionId) as AcpSessionState).status).toBe(
+      "cancelled",
+    );
+    expect((manager.getStatus(a2.acpSessionId) as AcpSessionState).status).toBe(
+      "cancelled",
+    );
+    expect((manager.getStatus(b1.acpSessionId) as AcpSessionState).status).toBe(
+      "running",
+    );
+
+    // AND the cancel reached each parent-A agent process exactly once.
+    expect(cancelCalls.sort()).toEqual(["proto-agent-a1", "proto-agent-a2"]);
+  });
+
+  test("returns 0 and dispatches nothing when the parent has no sessions", () => {
+    cancelCalls.length = 0;
+    const manager = new AcpSessionManager(5);
+
+    expect(manager.cancelForParent("parent-with-nothing")).toBe(0);
+    expect(cancelCalls).toEqual([]);
+  });
+});

package/src/acp/index.ts

@@ -18,6 +18,16 @@ export function getAcpSessionManager(): AcpSessionManager {
   return manager;
 }
 
+/**
+ * Returns the existing AcpSessionManager singleton, or null when none has been
+ * created yet. Use this on cleanup hot paths (e.g. cancelling a conversation)
+ * that must not spin up a manager just to discover there are no sessions to
+ * act on.
+ */
+export function peekAcpSessionManager(): AcpSessionManager | null {
+  return manager;
+}
+
 /**
  * Disposes the singleton AcpSessionManager and nulls the reference.
  */

package/src/acp/session-manager.ts

@@ -691,6 +691,41 @@ export class AcpSessionManager {
     }
   }
 
+  /**
+   * Cancels every in-flight session spawned by `parentConversationId`.
+   *
+   * Mirrors the subagent manager's `abortAllForParent`: when the user cancels
+   * a turn, the ACP agents it launched should stop rather than keep running in
+   * the background — holding a child process — and then, on completion, enqueue
+   * a follow-up message into the conversation the user just stopped. Cancelling
+   * settles each in-flight prompt down its `"cancelled"` path, which sends a
+   * client event but does NOT notify the parent, so no model activity follows
+   * the stop.
+   *
+   * Each session's `cancel()` runs detached (it awaits a protocol notification
+   * to the child) so callers on the cancel hot path never block on an
+   * unresponsive agent; failures are logged. Session ids are snapshotted before
+   * dispatch so concurrent teardown can't disturb the iteration. Returns the
+   * number of sessions a cancel was kicked off for.
+   */
+  cancelForParent(parentConversationId: string): number {
+    const ids: string[] = [];
+    for (const [acpSessionId, entry] of this.sessions) {
+      if (entry.parentConversationId === parentConversationId) {
+        ids.push(acpSessionId);
+      }
+    }
+    for (const acpSessionId of ids) {
+      void this.cancel(acpSessionId).catch((err) => {
+        log.warn(
+          { acpSessionId, parentConversationId, err },
+          "Failed to cancel ACP session on parent cancel",
+        );
+      });
+    }
+    return ids.length;
+  }
+
   /**
    * Kills the agent process and removes the session from tracking.
    *