@vellumai/assistant 0.8.1 → 0.8.2

package/src/filing/filing-service.ts

@@ -17,6 +17,11 @@ const log = getLogger("filing-service");
 
 const FILING_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
 
+// When compaction skips because a filing run holds the serialization lock,
+// retry on this near-term cadence so phase-aligned 24h timers don't starve
+// compaction across consecutive ticks.
+const COMPACTION_CONTENDED_RETRY_MS = 10 * 60 * 1000; // 10 minutes
+
 const FILING_PROMPT_TEMPLATE = `You are running a periodic knowledge base filing job. This is a background maintenance task focused on the buffer.
 
 Read \`pkb/buffer.md\`. For each item in the buffer:
@@ -66,6 +71,7 @@ This is your knowledge base — keep it sharp.`;
 
 export interface FilingDeps {
   getCurrentHour?: () => number;
+  compactionContendedRetryMs?: number;
 }
 
 export class FilingService {
@@ -79,8 +85,10 @@ export class FilingService {
   private readonly deps: FilingDeps;
   private timer: ReturnType<typeof setInterval> | null = null;
   private compactionTimer: ReturnType<typeof setInterval> | null = null;
+  private compactionRetryTimer: ReturnType<typeof setTimeout> | null = null;
   private activeRun: Promise<void> | null = null;
   private activeCompactionRun: Promise<void> | null = null;
+  private stopped = false;
   private _lastRunAt: number | null = null;
   private _nextRunAt: number | null = null;
   private _lastCompactionAt: number | null = null;
@@ -108,6 +116,7 @@ export class FilingService {
   }
 
   start(): void {
+    this.stopped = false;
     const fullConfig = getConfig();
     if (fullConfig.memory.v2.enabled) {
       log.info("Filing service disabled — memory v2 is active");
@@ -157,12 +166,14 @@ export class FilingService {
       clearInterval(this.compactionTimer);
       this.compactionTimer = null;
     }
+    this.clearCompactionRetry();
     this._nextRunAt = null;
     this._nextCompactionAt = null;
     this.start();
   }
 
   async stop(): Promise<void> {
+    this.stopped = true;
     if (this.timer) {
       clearInterval(this.timer);
       this.timer = null;
@@ -171,6 +182,7 @@ export class FilingService {
       clearInterval(this.compactionTimer);
       this.compactionTimer = null;
     }
+    this.clearCompactionRetry();
     this._nextRunAt = null;
     this._nextCompactionAt = null;
     const inflight: Promise<void>[] = [];
@@ -269,9 +281,13 @@ export class FilingService {
       log.debug(
         "Filing run in progress, skipping compaction to avoid concurrent PKB writes",
       );
+      this.scheduleCompactionRetry(
+        this.deps.compactionContendedRetryMs ?? COMPACTION_CONTENDED_RETRY_MS,
+      );
       return false;
     }
 
+    this.clearCompactionRetry();
     const run = this.executeCompactionRun();
     this.activeCompactionRun = run;
     try {
@@ -301,6 +317,29 @@ export class FilingService {
     this._nextCompactionAt = Date.now() + intervalMs;
   }
 
+  private scheduleCompactionRetry(delayMs: number): void {
+    this.clearCompactionRetry();
+    if (this.stopped) return;
+    this.compactionRetryTimer = setTimeout(() => {
+      this.compactionRetryTimer = null;
+      if (this.stopped) return;
+      this.runCompactionOnce().catch((err) => {
+        log.error({ err }, "Compaction retry failed");
+      });
+    }, delayMs);
+    // unref so the pending retry doesn't keep the daemon process alive on
+    // shutdown paths that don't call stop().
+    this.compactionRetryTimer.unref?.();
+    this._nextCompactionAt = Date.now() + delayMs;
+  }
+
+  private clearCompactionRetry(): void {
+    if (this.compactionRetryTimer) {
+      clearTimeout(this.compactionRetryTimer);
+      this.compactionRetryTimer = null;
+    }
+  }
+
   private shouldSkipForDiskPressure(source: "filing" | "compaction"): boolean {
     const diskPressureGate = checkDiskPressureBackgroundGate("background-work");
     if (diskPressureGate.action === "allow") return false;

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

@@ -47,12 +47,22 @@ mock.module("../../util/platform.js", () => ({
 
 // Stub config so heartbeat is enabled. Must export every symbol from
 // the real module because Bun's mock.module replaces the entire module.
-const stubConfig = {
+// Tests that need to flex maxConsecutiveRuns mutate this in-place.
+const stubConfig: {
+  heartbeat: {
+    enabled: boolean;
+    intervalMs: number;
+    activeHoursStart: number | null;
+    activeHoursEnd: number | null;
+    maxConsecutiveRuns: number | null;
+  };
+} = {
   heartbeat: {
     enabled: true,
     intervalMs: 60_000,
     activeHoursStart: null,
     activeHoursEnd: null,
+    maxConsecutiveRuns: null,
   },
 };
 mock.module("../../config/loader.js", () => ({
@@ -91,7 +101,6 @@ mock.module("../../prompts/system-prompt.js", () => ({
   SYSTEM_PROMPT_CACHE_BOUNDARY: "<<CACHE_BOUNDARY>>",
   buildCoreIdentityContext: () => "",
   buildSystemPrompt: () => "",
-  buildCliReferenceSection: () => "",
   ensurePromptFiles: () => {},
   stripCommentLines: (s: string) => s,
 }));
@@ -165,7 +174,6 @@ mock.module("../../runtime/pre-first-message-gate.js", () => ({
   hasReceivedUserMessage: () => preFirstMessageGateOpen,
 }));
 
-
 const { HeartbeatService } = await import("../heartbeat-service.js");
 
 let origWorkspaceDir: string | undefined;
@@ -178,6 +186,7 @@ beforeEach(() => {
   runBackgroundJobCalls.length = 0;
   skipHeartbeatRunCalls.length = 0;
   preFirstMessageGateOpen = true;
+  stubConfig.heartbeat.maxConsecutiveRuns = null;
   runBackgroundJobImpl = async () => ({
     conversationId: STUB_CONVERSATION_ID,
     ok: true,
@@ -351,9 +360,85 @@ describe("HeartbeatService", () => {
 
     expect(runBackgroundJobCalls).toHaveLength(1);
     expect(
-      skipHeartbeatRunCalls.some(
-        (c) => c.reason === "pre_first_user_message",
-      ),
+      skipHeartbeatRunCalls.some((c) => c.reason === "pre_first_user_message"),
     ).toBe(false);
   });
+
+  describe("max consecutive runs cap", () => {
+    test("skips with reason 'max_consecutive_runs' after the cap is hit", async () => {
+      stubConfig.heartbeat.maxConsecutiveRuns = 2;
+      const service = new HeartbeatService({ alerter: () => {} });
+
+      expect(await service.runOnce({ force: false })).toBe(true);
+      expect(await service.runOnce({ force: false })).toBe(true);
+      expect(await service.runOnce({ force: false })).toBe(false);
+
+      expect(runBackgroundJobCalls).toHaveLength(2);
+      expect(
+        skipHeartbeatRunCalls.some((c) => c.reason === "max_consecutive_runs"),
+      ).toBe(true);
+    });
+
+    test("resetTimer() clears the counter so auto runs resume", async () => {
+      stubConfig.heartbeat.maxConsecutiveRuns = 1;
+      const service = new HeartbeatService({ alerter: () => {} });
+      service.start();
+      try {
+        await service.runOnce({ force: false });
+        expect(await service.runOnce({ force: false })).toBe(false);
+
+        service.resetTimer();
+        expect(await service.runOnce({ force: false })).toBe(true);
+        expect(runBackgroundJobCalls).toHaveLength(2);
+      } finally {
+        await service.stop();
+      }
+    });
+
+    test("null disables the cap entirely", async () => {
+      stubConfig.heartbeat.maxConsecutiveRuns = null;
+      const service = new HeartbeatService({ alerter: () => {} });
+
+      for (let i = 0; i < 5; i++) {
+        expect(await service.runOnce({ force: false })).toBe(true);
+      }
+      expect(runBackgroundJobCalls).toHaveLength(5);
+      expect(
+        skipHeartbeatRunCalls.some((c) => c.reason === "max_consecutive_runs"),
+      ).toBe(false);
+    });
+
+    test("force runs bypass the cap and do not increment the counter", async () => {
+      stubConfig.heartbeat.maxConsecutiveRuns = 2;
+      const service = new HeartbeatService({ alerter: () => {} });
+
+      // Five force runs would push us well past the cap if force counted.
+      for (let i = 0; i < 5; i++) {
+        expect(await service.runOnce({ force: true })).toBe(true);
+      }
+      // Two auto runs should still proceed because the counter is at zero.
+      expect(await service.runOnce({ force: false })).toBe(true);
+      expect(await service.runOnce({ force: false })).toBe(true);
+      // The third auto run trips the cap.
+      expect(await service.runOnce({ force: false })).toBe(false);
+      expect(
+        skipHeartbeatRunCalls.some((c) => c.reason === "max_consecutive_runs"),
+      ).toBe(true);
+    });
+
+    test("reconfigure() resets the counter", async () => {
+      stubConfig.heartbeat.maxConsecutiveRuns = 1;
+      const service = new HeartbeatService({ alerter: () => {} });
+      service.start();
+      try {
+        await service.runOnce({ force: false });
+        expect(await service.runOnce({ force: false })).toBe(false);
+
+        service.reconfigure();
+        expect(await service.runOnce({ force: false })).toBe(true);
+      } finally {
+        await service.stop();
+      }
+    });
+  });
 });

package/src/heartbeat/heartbeat-run-store.ts

@@ -23,7 +23,8 @@ export type HeartbeatSkipReason =
   | "disabled"
   | "outside_active_hours"
   | "overlap"
-  | "pre_first_user_message";
+  | "pre_first_user_message"
+  | "max_consecutive_runs";
 
 export interface HeartbeatRunRecord {
   id: string;

package/src/heartbeat/heartbeat-service.ts

@@ -198,6 +198,10 @@ export class HeartbeatService {
   private _startupMissedCount = 0;
   private _startupCrashedCount = 0;
   private _hasRunStartupRecovery = false;
+  // Counter of consecutive auto-heartbeats since the last guardian message.
+  // Reset by resetTimer (guardian message), reconfigure, and stop. Force runs
+  // bypass the cap and do not increment.
+  private _consecutiveRuns = 0;
 
   constructor(deps: HeartbeatDeps) {
     this.deps = deps;
@@ -262,6 +266,11 @@ export class HeartbeatService {
               isAsyncBackground: true,
               visibleInSourceNow: false,
             },
+            conversationMetadata: {
+              source: "heartbeat",
+              groupId: "system:background",
+              conversationType: "background",
+            },
           }).catch((err) => {
             log.warn(
               { err },
@@ -350,6 +359,7 @@ export class HeartbeatService {
 
   /** Restart the timer with the latest config (e.g. after settings change). */
   reconfigure(): void {
+    this._consecutiveRuns = 0;
     this.configEpoch++;
     if (this._pendingRunId) {
       supersedePendingRun(this._pendingRunId);
@@ -371,6 +381,9 @@ export class HeartbeatService {
    * after an active conversation.
    */
   resetTimer(): void {
+    // Counter resets even when the timer is null so a guardian message during
+    // a stopped window still clears the count.
+    this._consecutiveRuns = 0;
     if (!this.timer) return;
     if (this.cronMode) {
       clearTimeout(this.timer as ReturnType<typeof setTimeout>);
@@ -390,6 +403,7 @@ export class HeartbeatService {
   }
 
   async stop(): Promise<void> {
+    this._consecutiveRuns = 0;
     this.stopped = true;
     if (this.timer) {
       clearTimeout(this.timer as ReturnType<typeof setTimeout>);
@@ -500,6 +514,28 @@ export class HeartbeatService {
       }
     }
 
+    // Cap consecutive auto-runs without a guardian message so the assistant
+    // stops burning LLM tokens when the user is away. Force runs (manual
+    // operator action) bypass the cap and do not increment the counter.
+    if (
+      !force &&
+      config.maxConsecutiveRuns != null &&
+      this._consecutiveRuns >= config.maxConsecutiveRuns
+    ) {
+      log.debug(
+        {
+          consecutiveRuns: this._consecutiveRuns,
+          maxConsecutiveRuns: config.maxConsecutiveRuns,
+        },
+        "Max consecutive runs reached, skipping",
+      );
+      if (runId) skipHeartbeatRun(runId, "max_consecutive_runs");
+      if (!this.cronMode) {
+        this.scheduleNextRun(config.intervalMs);
+      }
+      return false;
+    }
+
     // Overlap prevention
     if (this.activeRun) {
       log.debug("Previous heartbeat run still active, skipping");
@@ -525,6 +561,9 @@ export class HeartbeatService {
         this.activeRun = null;
       }
       this._lastRunAt = Date.now();
+      if (!force) {
+        this._consecutiveRuns++;
+      }
       if (!this.cronMode) {
         this.scheduleNextRun(getConfig().heartbeat.intervalMs);
       }
@@ -648,6 +687,7 @@ export class HeartbeatService {
           conversationMetadata: {
             source: "heartbeat",
             groupId: "system:background",
+            conversationType: "background",
           },
         });
       } catch (err) {
@@ -714,6 +754,7 @@ export class HeartbeatService {
       conversationMetadata: {
         source: "heartbeat",
         groupId: "system:background",
+        conversationType: "background",
       },
     });
   }

package/src/home/__tests__/feed-types.test.ts

@@ -82,6 +82,40 @@ describe("feedItemSchema — valid minimal items", () => {
     expect(parsed.expiresAt).toBe("2026-04-15T00:00:00.000Z");
     expect(parsed.detailPanel?.kind).toBe("emailDraft");
   });
+
+  test("category field passes through when present", () => {
+    for (const cat of [
+      "security",
+      "scheduling",
+      "background",
+      "email",
+      "system",
+    ] as const) {
+      const parsed = feedItemSchema.parse({
+        ...minimalNotification(),
+        category: cat,
+      });
+      expect(parsed.category).toBe(cat);
+    }
+  });
+
+  test("metadata field passes through when present", () => {
+    const parsed = feedItemSchema.parse({
+      ...minimalNotification(),
+      metadata: { subject: "Hello", count: 3, nested: { ok: true } },
+    });
+    expect(parsed.metadata).toEqual({
+      subject: "Hello",
+      count: 3,
+      nested: { ok: true },
+    });
+  });
+
+  test("items without category or metadata still parse (backward compat)", () => {
+    const parsed = feedItemSchema.parse(minimalNotification());
+    expect(parsed.category).toBeUndefined();
+    expect(parsed.metadata).toBeUndefined();
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -142,6 +176,12 @@ describe("feedItemSchema — enum validation", () => {
     }
   });
 
+  test("rejects unknown `category`", () => {
+    expect(() =>
+      feedItemSchema.parse({ ...minimalNotification(), category: "weather" }),
+    ).toThrow();
+  });
+
   test("rejects unknown `status`", () => {
     expect(() =>
       feedItemSchema.parse({ ...minimalNotification(), status: "archived" }),

package/src/home/feed-types.ts

@@ -38,6 +38,14 @@ export type FeedItemStatus = "new" | "seen" | "acted_on" | "dismissed";
 /** Visual urgency treatment — controls badge color independently of sort priority. */
 export type FeedItemUrgency = "low" | "medium" | "high" | "critical";
 
+/** Broad category for grouping and filtering feed items. */
+export type FeedItemCategory =
+  | "security"
+  | "scheduling"
+  | "background"
+  | "email"
+  | "system";
+
 /**
  * A single action button attached to a feed item.
  *
@@ -96,6 +104,10 @@ export interface FeedItem {
   conversationId?: string;
   /** Server-driven detail panel descriptor; when present, the client opens this panel kind. */
   detailPanel?: FeedItemDetailPanel;
+  /** Broad category for grouping and filtering feed items. */
+  category?: FeedItemCategory;
+  /** Arbitrary structured data the detail panel or other consumers can use. */
+  metadata?: Record<string, unknown>;
   /** Internal: ISO-8601 writer-record time, used for ordering + TTL. */
   createdAt: string;
 }
@@ -164,6 +176,14 @@ const feedItemDetailPanelSchema = z.object({
   kind: feedItemDetailPanelKindSchema,
 });
 
+const feedItemCategorySchema = z.enum([
+  "security",
+  "scheduling",
+  "background",
+  "email",
+  "system",
+]);
+
 /**
  * Schema for a single `FeedItem`.
  *
@@ -187,6 +207,8 @@ export const feedItemSchema = z.object({
   urgency: feedItemUrgencySchema.optional(),
   conversationId: z.string().optional(),
   detailPanel: feedItemDetailPanelSchema.optional(),
+  category: feedItemCategorySchema.optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
   createdAt: z.string(),
 });
 

package/src/home/post-connect-feed.ts

@@ -44,6 +44,7 @@ export async function emitPostConnectNudge(service: string): Promise<void> {
       "I can triage your inbox, summarize new emails, or draft replies to important threads.",
     timestamp: now.toISOString(),
     status: "new",
+    category: "email",
     expiresAt,
     createdAt: now.toISOString(),
     actions: [

package/src/index.ts

@@ -1,5 +1,22 @@
 #!/usr/bin/env bun
 
+import { red } from "./cli/lib/cli-colors.js";
+import {
+  detectUnknownCommand,
+  formatUnknownCommandMessage,
+} from "./cli/lib/unknown-command.js";
 import { buildCliProgram } from "./cli/program.js";
 
-(await buildCliProgram()).parse();
+const program = await buildCliProgram();
+
+// Commander processes `--help` before any action or hook fires, so
+// `assistant <unknown> --help` would dump the root help instead of flagging
+// the typo. Pre-scan argv so the unknown-command error wins over the help
+// short-circuit. See cli/lib/unknown-command.ts.
+const unknown = detectUnknownCommand(program, process.argv.slice(2));
+if (unknown) {
+  process.stderr.write(`${red(formatUnknownCommandMessage(unknown))}\n`);
+  process.exit(1);
+}
+
+program.parse();

package/src/live-voice/__tests__/live-voice-stt.test.ts

@@ -229,6 +229,63 @@ describe("LiveVoiceSession STT", () => {
     ]);
   });
 
+  test("retains transcriber handle when stop() throws so close() can clean up", async () => {
+    class ThrowingStopTranscriber extends MockStreamingTranscriber {
+      stopCalls = 0;
+      override stop(): void {
+        this.stopCalls += 1;
+        if (this.stopCalls === 1) {
+          throw new Error("stop failed");
+        }
+      }
+    }
+
+    const transcriber = new ThrowingStopTranscriber();
+    const { frames, session } = createSessionWithTranscriber(transcriber);
+
+    await session.start();
+    await session.handleClientFrame({ type: "ptt_release" });
+
+    expect(transcriber.stopCalls).toBe(1);
+    expect(
+      frames.some(
+        (frame) =>
+          frame.type === "error" &&
+          frame.message.includes(
+            "Live voice transcription could not be stopped",
+          ),
+      ),
+    ).toBe(true);
+
+    await session.close("websocket_close");
+
+    expect(transcriber.stopCalls).toBe(2);
+  });
+
+  test("retains transcriber handle when stop() throws so interrupt() can clean up", async () => {
+    class ThrowingStopTranscriber extends MockStreamingTranscriber {
+      stopCalls = 0;
+      override stop(): void {
+        this.stopCalls += 1;
+        if (this.stopCalls === 1) {
+          throw new Error("stop failed");
+        }
+      }
+    }
+
+    const transcriber = new ThrowingStopTranscriber();
+    const { session } = createSessionWithTranscriber(transcriber);
+
+    await session.start();
+    await session.handleClientFrame({ type: "ptt_release" });
+
+    expect(transcriber.stopCalls).toBe(1);
+
+    await session.handleClientFrame({ type: "interrupt" });
+
+    expect(transcriber.stopCalls).toBe(2);
+  });
+
   test("uses the production streaming transcriber resolver by default", () => {
     const source = readFileSync(
       new URL("../live-voice-session.ts", import.meta.url),

package/src/mcp/client.ts

@@ -14,6 +14,24 @@ const log = getLogger("mcp-client");
 
 const CONNECT_TIMEOUT_MS = 30_000;
 
+// MCP servers occasionally return tools with a missing or non-object
+// `inputSchema` (spec violation, but seen in the wild). Coerce to a valid
+// empty object schema so downstream code that assumes `input_schema: object`
+// (e.g. `injectActivityField`) doesn't crash.
+function normalizeInputSchema(
+  raw: unknown,
+  toolName: string,
+): Record<string, unknown> {
+  if (raw != null && typeof raw === "object" && !Array.isArray(raw)) {
+    return raw as Record<string, unknown>;
+  }
+  log.warn(
+    { toolName, received: typeof raw },
+    "MCP tool returned non-object inputSchema; defaulting to empty object schema",
+  );
+  return { type: "object", properties: {} };
+}
+
 export interface McpToolInfo {
   name: string;
   description: string;
@@ -80,9 +98,7 @@ export class McpClient {
         `mcp:${this.serverId}:tokens`,
       );
       if (cachedTokens) {
-        const callbackTransport = getIsPlatform()
-          ? "gateway"
-          : "loopback";
+        const callbackTransport = getIsPlatform() ? "gateway" : "loopback";
         this.oauthProvider = new McpOAuthProvider(
           this.serverId,
           transportConfig.url,
@@ -164,7 +180,7 @@ export class McpClient {
     return result.tools.map((tool) => ({
       name: tool.name,
       description: tool.description ?? "",
-      inputSchema: tool.inputSchema as Record<string, unknown>,
+      inputSchema: normalizeInputSchema(tool.inputSchema, tool.name),
     }));
   }
 

package/src/media/image-credentials.ts

@@ -8,8 +8,8 @@
  * credentials are unavailable.
  */
 
-import { MANAGED_PROVIDER_META } from "../providers/managed-proxy/constants.js";
-import { resolveManagedProxyContext } from "../providers/managed-proxy/context.js";
+import { PLATFORM_PROVIDER_META } from "../providers/platform-proxy/constants.js";
+import { resolveManagedProxyContext } from "../providers/platform-proxy/context.js";
 import { getProviderKeyAsync } from "../security/secure-keys.js";
 import type { ImageGenCredentials, ImageGenProvider } from "./types.js";
 
@@ -33,7 +33,7 @@ export async function resolveImageGenCredentials(opts: {
     // Resolve platform URL + assistant API key from a single snapshot so
     // baseUrl and assistantApiKey can't diverge if the credential is cleared
     // between lookups.
-    const meta = MANAGED_PROVIDER_META[provider];
+    const meta = PLATFORM_PROVIDER_META[provider];
     const ctx = await resolveManagedProxyContext();
     if (
       !meta?.managed ||