@vellumai/assistant 0.12.4-dev.202609232115.73e8b74 → 0.12.4-dev.202609232312.d1432a4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.4-dev.202609232115.73e8b74",
+  "version": "0.12.4-dev.202609232312.d1432a4",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/daemon/activity-trail.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Tests for the daemon activity trail. A block report asks "what overlapped
+ * the last N ms", so the trail must include work still running, include work
+ * that ended inside the window, exclude work that ended before it, and group
+ * identical labels so the report stays small.
+ */
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import type { InterfaceId } from "../channels/types.js";
+import {
+  getActivityOverlapping,
+  resetActivityTrailForTests,
+  trackDaemonActivity,
+  turnActivityLabel,
+  turnConversationType,
+} from "./activity-trail.js";
+
+/** Resolves after `ms` of wall time. */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+beforeEach(() => {
+  resetActivityTrailForTests();
+});
+
+describe("getActivityOverlapping", () => {
+  test("reports running work and work that ended inside the window", async () => {
+    // GIVEN a background turn that has ended and a user turn still running
+    await trackDaemonActivity({ kind: "schedule_tick" }, async () => {});
+    let release!: () => void;
+    const userTurn = trackDaemonActivity(
+      {
+        kind: "turn",
+        conversationType: "standard",
+        callSite: "mainAgent",
+        turnInterface: "web",
+        interactive: true,
+      },
+      () => new Promise<void>((resolve) => (release = resolve)),
+    );
+
+    // WHEN the last minute is queried
+    const groups = getActivityOverlapping(60_000);
+
+    // THEN both appear, the user turn marked as running
+    expect(groups).toHaveLength(2);
+    expect(groups).toContainEqual(
+      expect.objectContaining({ kind: "schedule_tick", count: 1, running: 0 }),
+    );
+    expect(groups).toContainEqual(
+      expect.objectContaining({
+        kind: "turn",
+        turnInterface: "web",
+        interactive: true,
+        running: 1,
+      }),
+    );
+    release();
+    await userTurn;
+  });
+
+  test("excludes work that ended before the window began", async () => {
+    // GIVEN work that ended ~50ms ago
+    await trackDaemonActivity({ kind: "git_compaction" }, async () => {});
+    await sleep(50);
+
+    // WHEN only the last 10ms are queried
+    const groups = getActivityOverlapping(10);
+
+    // THEN it is not attributed to the window
+    expect(groups).toEqual([]);
+  });
+
+  test("groups identical labels and keeps the longest duration", async () => {
+    // GIVEN three heartbeat turns, one noticeably longer
+    const heartbeat = {
+      kind: "turn" as const,
+      conversationType: "background" as const,
+      callSite: "heartbeatAgent" as const,
+      interactive: false,
+    };
+    await trackDaemonActivity(heartbeat, async () => {});
+    await trackDaemonActivity(heartbeat, () => sleep(30));
+    await trackDaemonActivity(heartbeat, async () => {});
+
+    // WHEN the window covers all three
+    const groups = getActivityOverlapping(60_000);
+
+    // THEN they collapse into one group
+    expect(groups).toHaveLength(1);
+    expect(groups[0]).toMatchObject({ ...heartbeat, count: 3, running: 0 });
+    expect(groups[0]!.longestMs).toBeGreaterThanOrEqual(25);
+  });
+
+  test("a failing job still closes its mark", async () => {
+    // GIVEN tracked work that throws
+    await expect(
+      trackDaemonActivity({ kind: "vbundle_export" }, async () => {
+        throw new Error("boom");
+      }),
+    ).rejects.toThrow("boom");
+
+    // WHEN the trail is queried
+    const groups = getActivityOverlapping(60_000);
+
+    // THEN the work is recorded as ended, not left running forever
+    expect(groups).toEqual([
+      expect.objectContaining({ kind: "vbundle_export", running: 0 }),
+    ]);
+  });
+});
+
+describe("burst retention", () => {
+  test("a burst of finished work does not evict what overlapped a block", async () => {
+    // GIVEN a user turn that ends, then a burst of 500 short jobs
+    await trackDaemonActivity(
+      { kind: "turn", conversationType: "standard", callSite: "mainAgent" },
+      async () => {},
+    );
+    for (let i = 0; i < 500; i++) {
+      await trackDaemonActivity({ kind: "schedule_tick" }, async () => {});
+    }
+
+    // WHEN the last minute is queried
+    const groups = getActivityOverlapping(60_000);
+
+    // THEN the earlier turn is still attributed
+    expect(groups).toContainEqual(
+      expect.objectContaining({ kind: "turn", count: 1 }),
+    );
+    expect(groups).toContainEqual(
+      expect.objectContaining({ kind: "schedule_tick", count: 500 }),
+    );
+  });
+});
+
+describe("turnActivityLabel", () => {
+  function conversation(opts: {
+    isSubagent?: boolean;
+    originInterface?: InterfaceId;
+    liveInterface?: InterfaceId;
+  }) {
+    return {
+      conversationType: "standard",
+      isSubagent: opts.isSubagent ?? false,
+      originInterface: opts.originInterface,
+      getTurnInterfaceContext: () =>
+        opts.liveInterface
+          ? { userMessageInterface: opts.liveInterface }
+          : null,
+    };
+  }
+
+  test("a subagent turn without an explicit call site is a subagent turn", () => {
+    // GIVEN a subagent conversation and a queue-drained turn with no call site
+    // WHEN its label is built
+    const label = turnActivityLabel(
+      conversation({ isSubagent: true }),
+      undefined,
+      false,
+    );
+    // THEN it matches the call site the loop resolves, not mainAgent
+    expect(label.callSite).toBe("subagentSpawn");
+  });
+
+  test("an explicit call site wins", () => {
+    const label = turnActivityLabel(conversation({}), "heartbeatAgent", false);
+    expect(label.callSite).toBe("heartbeatAgent");
+  });
+
+  test("the turn's own interface wins over the conversation's origin", () => {
+    // GIVEN a conversation started on web, now continued from Slack
+    // WHEN the Slack turn's label is built
+    const label = turnActivityLabel(
+      conversation({ originInterface: "web", liveInterface: "slack" }),
+      undefined,
+      true,
+    );
+    // THEN it is attributed to Slack
+    expect(label.turnInterface).toBe("slack");
+    expect(label.interactive).toBe(true);
+  });
+
+  test("falls back to the origin interface, and omits it when unknown", () => {
+    expect(
+      turnActivityLabel(
+        conversation({ originInterface: "macos" }),
+        undefined,
+        false,
+      ).turnInterface,
+    ).toBe("macos");
+    expect(
+      turnActivityLabel(conversation({}), undefined, false),
+    ).not.toHaveProperty("turnInterface");
+  });
+});
+
+describe("turnConversationType", () => {
+  test("keeps known types, defaults a missing one, and buckets the rest", () => {
+    expect(turnConversationType("background")).toBe("background");
+    expect(turnConversationType("scheduled")).toBe("scheduled");
+    expect(turnConversationType(undefined)).toBe("standard");
+    expect(turnConversationType("something-new")).toBe("other");
+  });
+});

package/src/daemon/activity-trail.ts

@@ -0,0 +1,190 @@
+/**
+ * Recent work this process ran, so an event-loop block report can say what
+ * was running while the loop was blocked.
+ *
+ * The section trail (`persistence/slow-sync-log.ts`) names instrumented
+ * synchronous sections, which cover a small share of blocks. This trail
+ * records coarse units of work instead: every agent turn, labelled by
+ * conversation type, call site, and interface, plus the non-turn background
+ * jobs that run on the daemon (the scheduler tick, bundle export and import,
+ * the channel retry sweep, git history compaction). A block report groups
+ * the entries that overlap its window, which
+ * answers whether background work shared the loop with a user-facing turn.
+ *
+ * Labels are closed sets (no free-form strings), so the grouped result is
+ * safe to send as telemetry. The trail is per process; only the daemon
+ * reports it.
+ */
+
+import type { InterfaceId } from "../channels/types.js";
+import type { LLMCallSite } from "../config/schemas/llm.js";
+import type { Conversation } from "./conversation.js";
+import { resolveTurnCallSite } from "./turn-call-site.js";
+
+export type DaemonActivityKind =
+  | "turn"
+  | "schedule_tick"
+  | "vbundle_export"
+  | "vbundle_import"
+  | "channel_retry_sweep"
+  | "git_compaction";
+
+/** Conversation types a turn label carries; anything else is "other". */
+const TURN_CONVERSATION_TYPES = new Set([
+  "standard",
+  "background",
+  "scheduled",
+]);
+
+export interface DaemonActivityLabel {
+  kind: DaemonActivityKind;
+  /** Turns only: the conversation's type. */
+  conversationType?: "standard" | "background" | "scheduled" | "other";
+  /** Turns only: the LLM call site the turn runs under. */
+  callSite?: LLMCallSite;
+  /**
+   * Turns only: the interface of the message that started the turn, else
+   * the interface the conversation came from.
+   */
+  turnInterface?: InterfaceId;
+  /** Turns only: whether a client is attached and waiting on the reply. */
+  interactive?: boolean;
+}
+
+export interface DaemonActivityGroup extends DaemonActivityLabel {
+  /** Entries with this label that overlapped the window. */
+  count: number;
+  /** Of those, how many were still running at report time. */
+  running: number;
+  /** Longest single entry, clamped to the report time for running ones. */
+  longestMs: number;
+}
+
+interface ActivityMark {
+  label: DaemonActivityLabel;
+  startedAt: number;
+  endedAt?: number;
+}
+
+/**
+ * Ended entries are kept for this long, so a block of up to this length can
+ * still see the work that overlapped it, however much ended meanwhile.
+ */
+const ENDED_MARK_RETENTION_MS = 30 * 60_000;
+/** Hard cap on ended entries, bounding memory under a pathological burst. */
+const MAX_ENDED_MARKS = 2_000;
+/** Cap on groups in one report, keeping it inside the telemetry byte budget. */
+const MAX_GROUPS = 10;
+
+const runningMarks = new Set<ActivityMark>();
+const endedMarks: ActivityMark[] = [];
+
+/** Narrow a conversation's stored type to the closed label set. */
+export function turnConversationType(
+  value: string | undefined,
+): DaemonActivityLabel["conversationType"] {
+  if (value === undefined) {
+    return "standard";
+  }
+  return TURN_CONVERSATION_TYPES.has(value)
+    ? (value as "standard" | "background" | "scheduled")
+    : "other";
+}
+
+/**
+ * The label for a turn about to run on `conversation`. Uses the same
+ * call-site default and interface precedence as the agent loop: the
+ * interface of the message that started the turn, else the conversation's
+ * origin interface.
+ */
+export function turnActivityLabel(
+  conversation: Pick<
+    Conversation,
+    "conversationType" | "isSubagent" | "originInterface"
+  > & {
+    getTurnInterfaceContext(): { userMessageInterface?: InterfaceId } | null;
+  },
+  explicitCallSite: LLMCallSite | undefined,
+  isInteractive: boolean | undefined,
+): DaemonActivityLabel {
+  const turnInterface =
+    conversation.getTurnInterfaceContext()?.userMessageInterface ??
+    conversation.originInterface;
+  return {
+    kind: "turn",
+    conversationType: turnConversationType(conversation.conversationType),
+    callSite: resolveTurnCallSite(explicitCallSite, conversation),
+    ...(turnInterface ? { turnInterface } : {}),
+    interactive: isInteractive ?? false,
+  };
+}
+
+/** Run `fn` as a unit of tracked work. The mark closes however `fn` settles. */
+export async function trackDaemonActivity<T>(
+  label: DaemonActivityLabel,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const mark: ActivityMark = { label, startedAt: performance.now() };
+  runningMarks.add(mark);
+  try {
+    return await fn();
+  } finally {
+    mark.endedAt = performance.now();
+    runningMarks.delete(mark);
+    endedMarks.push(mark);
+    // Marks end in order, so the oldest are at the front.
+    const cutoff = mark.endedAt - ENDED_MARK_RETENTION_MS;
+    let expired = 0;
+    while (
+      expired < endedMarks.length &&
+      (endedMarks[expired]!.endedAt! < cutoff ||
+        endedMarks.length - expired > MAX_ENDED_MARKS)
+    ) {
+      expired++;
+    }
+    endedMarks.splice(0, expired);
+  }
+}
+
+/**
+ * Work that overlapped the last `windowMs`, grouped by label, longest first.
+ * A mark overlaps when it started before `now` and had not ended before the
+ * window began.
+ */
+export function getActivityOverlapping(
+  windowMs: number,
+  now: number = performance.now(),
+): DaemonActivityGroup[] {
+  const windowStart = now - windowMs;
+  const groups = new Map<string, DaemonActivityGroup>();
+  for (const mark of [...runningMarks, ...endedMarks]) {
+    const end = mark.endedAt ?? now;
+    if (mark.startedAt > now || end < windowStart) {
+      continue;
+    }
+    const key = JSON.stringify(mark.label);
+    const durationMs = Math.round(end - mark.startedAt);
+    const group = groups.get(key);
+    if (group) {
+      group.count++;
+      group.running += mark.endedAt === undefined ? 1 : 0;
+      group.longestMs = Math.max(group.longestMs, durationMs);
+    } else {
+      groups.set(key, {
+        ...mark.label,
+        count: 1,
+        running: mark.endedAt === undefined ? 1 : 0,
+        longestMs: durationMs,
+      });
+    }
+  }
+  return [...groups.values()]
+    .sort((a, b) => b.longestMs - a.longestMs)
+    .slice(0, MAX_GROUPS);
+}
+
+/** Test isolation only: the trail is process-global module state. */
+export function resetActivityTrailForTests(): void {
+  runningMarks.clear();
+  endedMarks.length = 0;
+}

package/src/daemon/conversation-media-retry.ts

@@ -294,7 +294,7 @@ export async function raceWithTimeout<T>(
 ): Promise<"completed" | "timed_out"> {
   let timer: ReturnType<typeof setTimeout> | undefined;
   try {
-    const result = await Promise.race([
+    return await Promise.race([
       promise.then(
         () => "completed" as const,
         () => "completed" as const,
@@ -303,7 +303,6 @@ export async function raceWithTimeout<T>(
         timer = setTimeout(() => resolve("timed_out"), timeoutMs);
       }),
     ]);
-    return result;
   } finally {
     if (timer !== undefined) {
       clearTimeout(timer);

package/src/daemon/conversation.ts

@@ -118,6 +118,7 @@ import { getLogger } from "../util/logger.js";
 import { withSqliteRetry } from "../util/sqlite-retry.js";
 import type { WorkspaceGitService } from "../workspace/git-service.js";
 import type { commitTurnChanges } from "../workspace/turn-commit.js";
+import { trackDaemonActivity, turnActivityLabel } from "./activity-trail.js";
 import type { AssistantAttachmentDraft } from "./assistant-attachments.js";
 import { BrowserModeSessionProducer } from "./browser-mode-session.js";
 import { ComputerUseModeSessionProducer } from "./computer-use-mode-session.js";
@@ -3558,12 +3559,16 @@ export class Conversation {
     },
   ): Promise<void> {
     const { onEvent, ...rest } = options ?? {};
-    return runAgentLoopImpl(
-      this,
-      content,
-      userMessageId,
-      onEvent ?? this.emit,
-      rest,
+    return trackDaemonActivity(
+      turnActivityLabel(this, options?.callSite, options?.isInteractive),
+      () =>
+        runAgentLoopImpl(
+          this,
+          content,
+          userMessageId,
+          onEvent ?? this.emit,
+          rest,
+        ),
     );
   }
 

package/src/daemon/event-loop-watchdog.test.ts

@@ -6,11 +6,112 @@
  *   a healthy loop never reports.
  * - `start`/`stop` must be idempotent and safe to call in any order so daemon
  *   startup and the two shutdown paths can call them unconditionally.
+ * - `buildBlockTelemetryDetail` must never send conversation titles and must
+ *   always fit the server's detail byte cap, since an oversize bag drops the
+ *   whole report.
  */
 import { describe, expect, test } from "bun:test";
 
-const { evaluateTick, startEventLoopWatchdog, stopEventLoopWatchdog } =
-  await import("./event-loop-watchdog.js");
+import type { StallCapture } from "../monitoring/stall-capture.js";
+import type { SectionTrailEntry } from "../persistence/slow-sync-log.js";
+import type { DaemonActivityGroup } from "./activity-trail.js";
+
+const {
+  buildBlockTelemetryDetail,
+  detailFitsServerCap,
+  evaluateTick,
+  startEventLoopWatchdog,
+  stopEventLoopWatchdog,
+} = await import("./event-loop-watchdog.js");
+
+function captureWith(conversationCount: number): StallCapture {
+  return {
+    ts: 1,
+    daemonPid: 1,
+    heartbeatAgeMs: 21_000,
+    kernelStack: "[<0>] do_epoll_wait+0x4a0/0x4e0\n".repeat(12),
+    processState: "S",
+    waitState: {
+      syscall: 232,
+      epoll: {
+        fd: 7,
+        watched: 1,
+        listeningSockets: 0,
+        sockets: 0,
+        pipes: 1,
+        eventfds: 0,
+        timerfds: 0,
+        other: 0,
+      },
+      children: [{ pid: 200, comm: "git", state: "R", ageMs: 20_000 }],
+      threads: Array.from({ length: 8 }, (_, i) => ({
+        comm: `Bun Pool ${i}`,
+        state: "S",
+        wchan: "futex_wait_queue",
+        count: 1,
+      })),
+    },
+    sample: {
+      ts: 1,
+      memory: null,
+      memoryStat: null,
+      reclaim: null,
+      cpu: null,
+      events: null,
+      deltas: null,
+      disk: null,
+      processes: [
+        ...Array.from({ length: 6 }, (_, i) => ({
+          pid: 100 + i,
+          name: i === 0 ? "memory-worker" : `chrome-${i}`,
+          cpuPct: 150 - i * 10,
+          rssMb: 800,
+        })),
+        { pid: 1, name: "daemon", cpuPct: 4, rssMb: 900 },
+      ],
+      activeConversations: Array.from(
+        { length: conversationCount },
+        (_, i) => ({
+          conversationId: `01a0c9a0-0000-7000-8000-00000000000${i % 10}`,
+          title:
+            "A long title drawn from the user's own first message x".repeat(2),
+          originChannel: "vellum",
+          originInterface: "web",
+          processingStartedAt: 1,
+        }),
+      ),
+    },
+  };
+}
+
+/** The report's maximum of 10 activity groups, longest (a user turn) first. */
+const fullActivity: DaemonActivityGroup[] = [
+  {
+    kind: "turn",
+    conversationType: "standard",
+    callSite: "mainAgent",
+    turnInterface: "web",
+    interactive: true,
+    count: 1,
+    running: 1,
+    longestMs: 90_000,
+  },
+  ...Array.from({ length: 9 }, (_, i) => ({
+    kind: "turn" as const,
+    conversationType: "background" as const,
+    callSite: "heartbeatAgent" as const,
+    interactive: false,
+    count: i + 1,
+    running: 0,
+    longestMs: 60_000 - i,
+  })),
+];
+
+const trail: SectionTrailEntry[] = Array.from({ length: 16 }, (_, i) => ({
+  label: "conversation-crud:get-messages",
+  startedAgoMs: 100_000 + i * 1_000,
+  endedAgoMs: 99_000 + i * 1_000,
+}));
 
 describe("evaluateTick", () => {
   const INTERVAL = 1_000;
@@ -78,3 +179,101 @@ describe("start/stop lifecycle", () => {
     expect(() => stopEventLoopWatchdog()).not.toThrow();
   });
 });
+
+describe("buildBlockTelemetryDetail", () => {
+  test("never sends conversation titles", () => {
+    // GIVEN a capture whose active conversations carry titles
+    // WHEN the telemetry detail is built
+    const detail = buildBlockTelemetryDetail({
+      thresholdMs: 5_000,
+      daemonUptimeMs: 60_000,
+      activity: [],
+      sectionTrail: [],
+      stallCapture: captureWith(2),
+    });
+    // THEN every title is nulled but the rest of the entry is kept
+    const conversations = detail.stall_capture!.sample.activeConversations!;
+    expect(conversations).toHaveLength(2);
+    expect(conversations.every((c) => c.title === null)).toBe(true);
+    expect(conversations[0]!.originInterface).toBe("web");
+  });
+
+  test("does not mutate the caller's capture", () => {
+    // GIVEN a capture the caller also logs locally
+    const capture = captureWith(2);
+    // WHEN the telemetry detail is built
+    buildBlockTelemetryDetail({
+      thresholdMs: 5_000,
+      daemonUptimeMs: 60_000,
+      activity: [],
+      sectionTrail: trail,
+      stallCapture: capture,
+    });
+    // THEN the local copy still has its titles
+    expect(capture.sample.activeConversations![0]!.title).not.toBeNull();
+  });
+
+  test("a small report is sent untrimmed", () => {
+    // GIVEN a report well under the byte cap
+    // WHEN the telemetry detail is built
+    const detail = buildBlockTelemetryDetail({
+      thresholdMs: 5_000,
+      daemonUptimeMs: 60_000,
+      activity: [],
+      sectionTrail: trail.slice(0, 2),
+      stallCapture: captureWith(1),
+    });
+    // THEN nothing is trimmed and the wait state survives intact
+    expect(detail.trimmed).toBeUndefined();
+    expect(detail.stall_capture!.waitState!.threads).toHaveLength(8);
+  });
+
+  test("an oversize report is trimmed to fit, keeping the wait state", () => {
+    // GIVEN a full trail and many active conversations (the heavy-user case)
+    // WHEN the telemetry detail is built
+    const detail = buildBlockTelemetryDetail({
+      thresholdMs: 5_000,
+      daemonUptimeMs: 60_000,
+      activity: fullActivity,
+      sectionTrail: trail,
+      stallCapture: captureWith(20),
+    });
+    // THEN it fits the server cap, records what was trimmed, and still
+    // carries the attribution the report exists for
+    expect(detailFitsServerCap(detail)).toBe(true);
+    expect(detail.trimmed!.length).toBeGreaterThan(0);
+    expect(detail.stall_capture!.waitState!.epoll!.pipes).toBe(1);
+    expect(detail.stall_capture!.waitState!.children).toHaveLength(1);
+    expect(detail.activity.length).toBeGreaterThanOrEqual(4);
+    expect(
+      detail.stall_capture!.sample.processes!.length,
+    ).toBeGreaterThanOrEqual(3);
+    expect(detail.stall_capture!.sample.processes![0]!.name).toBe(
+      "memory-worker",
+    );
+    // Trimming keeps the daemon for comparison.
+    expect(
+      detail.stall_capture!.sample.processes!.some((p) => p.name === "daemon"),
+    ).toBe(true);
+    expect(detail.activity[0]).toMatchObject({
+      kind: "turn",
+      conversationType: "standard",
+    });
+  });
+});
+
+describe("detailFitsServerCap", () => {
+  test("ignores undefined keys, which serialization drops", () => {
+    // GIVEN a small detail with an undefined field
+    // WHEN it is checked against the server cap
+    // THEN the undefined key does not count as an invalid payload
+    expect(detailFitsServerCap({ a: 1, b: undefined })).toBe(true);
+  });
+
+  test("rejects a detail over the server cap", () => {
+    // GIVEN a detail larger than 4096 serialized bytes
+    // WHEN it is checked against the server cap
+    // THEN it does not fit
+    expect(detailFitsServerCap({ blob: "x".repeat(5_000) })).toBe(false);
+  });
+});