@vellumai/assistant 0.8.12 → 0.9.0-staging.1

package/src/runtime/assistant-stream-state.ts

@@ -20,10 +20,16 @@
  * - Total size: 256 KB
  * - Age: 30 seconds
  *
- * The ring is in-memory and per-daemon-process. After a daemon restart
- * the seq resets and reconnecting clients fall through to the snapshot
- * path. The ring is sized generously enough that a typical refresh
- * round-trip (~1-3s) is well within window.
+ * The ring is in-memory and per-daemon-process, but the seq counter
+ * itself survives restarts: blocks of seq values are reserved ahead of
+ * use and the reserved ceiling is persisted to the workspace
+ * (`data/stream-seq.json`), so a restarted daemon resumes stamping
+ * above every seq the previous process could have emitted. Clients
+ * therefore never observe the counter moving backwards — a restart
+ * shows up as (at most) a bounded forward gap, which the normal
+ * gap-reconcile / snapshot-resync path already handles. The ring is
+ * sized generously enough that a typical refresh round-trip (~1-3s)
+ * is well within window.
  *
  * Persisted-seq map: alongside the live counter and ring, this module
  * tracks, per conversation, the `seq` of the last event whose content is
@@ -34,12 +40,17 @@
  * persistence flush (assistant rows persist incrementally, debounced, so
  * the snapshot can lag the live counter) -- never the live counter
  * itself, which would over-claim events that have streamed but not yet
- * been written. It shares the live counter's lifetime by design: both
- * are in-memory and reset together on restart, so a stored value can
- * never dangle against a fresh counter. The map is LRU-bounded; an
+ * been written. The map is in-memory and clears on restart; because the
+ * counter resumes above the persisted reservation, a value recorded by
+ * a previous process could only ever be lower than any seq the new
+ * process assigns -- never ambiguous against it. The map is LRU-bounded; an
  * evicted conversation reports no seq and the client cold-starts.
  */
 
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { getWorkspaceDir } from "../util/platform.js";
 import type { AssistantEvent } from "./assistant-event.js";
 
 // ── Tunables ─────────────────────────────────────────────────────────
@@ -58,6 +69,15 @@ const RING_AGE_LIMIT_MS = 30_000;
  */
 const PERSISTED_SEQ_CONVERSATION_LIMIT = 1024;
 
+/**
+ * How many seq values are reserved per persisted write. The counter can
+ * hand out seqs up to the persisted ceiling without touching disk, so
+ * the file is written once per block rather than once per event. A
+ * restart skips at most one block's worth of unused seqs — a bounded
+ * forward gap that clients already treat as a missed-events signal.
+ */
+const SEQ_RESERVATION_BLOCK = 1024;
+
 // ── Types ────────────────────────────────────────────────────────────
 
 /**
@@ -97,6 +117,21 @@ interface RingEntry {
 
 interface AssistantStreamState {
   nextSeq: number;
+  /**
+   * Highest seq this process may assign without persisting a new
+   * reservation. `0` until the first stamp loads (or creates) the
+   * persisted reservation.
+   */
+  reservedSeqCeiling: number;
+  /** Whether the persisted reservation has been loaded this process. */
+  seqReservationLoaded: boolean;
+  /**
+   * Seq of the first event stamped by this process, or `0` before any
+   * stamp. Distinguishes a reservation skip (seqs below this value were
+   * never assigned by this process, so nothing is missing from the
+   * ring) from genuine ring eviction when judging replay validity.
+   */
+  firstStampedSeq: number;
   ring: RingEntry[];
   totalSizeBytes: number;
   /**
@@ -112,6 +147,9 @@ interface AssistantStreamState {
 
 const state: AssistantStreamState = {
   nextSeq: 1,
+  reservedSeqCeiling: 0,
+  seqReservationLoaded: false,
+  firstStampedSeq: 0,
   ring: [],
   totalSizeBytes: 0,
   persistedSeqByConversation: new Map(),
@@ -138,7 +176,9 @@ export function stampAndBuffer(
 ): void {
   if (event.conversationId == null) return;
 
+  reserveSeqCapacity();
   event.seq = state.nextSeq++;
+  if (state.firstStampedSeq === 0) state.firstStampedSeq = event.seq;
 
   // Approximate size by serialized JSON length. This is the same
   // bytes-on-wire we'll send, so it tracks ring memory pressure
@@ -187,8 +227,16 @@ export function getReplayWindow(
 
   if (state.ring.length === 0) return [];
 
+  // A cursor from before this process started can skip over the
+  // reservation gap: seqs below `firstStampedSeq` were never assigned
+  // by this process, so as long as the ring still holds everything
+  // this process stamped, no replayable event is missing. (Events from
+  // the previous process are unrecoverable either way — clients catch
+  // up on those via the snapshot path, triggered by the seq jump.)
   const oldest = state.ring[0]?.seq ?? Infinity;
-  if (lastSeenSeq < oldest - 1) return null;
+  const coversRestartGap =
+    lastSeenSeq < state.firstStampedSeq && oldest === state.firstStampedSeq;
+  if (lastSeenSeq < oldest - 1 && !coversRestartGap) return null;
 
   return state.ring
     .filter(
@@ -260,6 +308,26 @@ export function getPersistedSeq(conversationId: string): number | null {
  */
 export function _resetStreamStateForTesting(): void {
   state.nextSeq = 1;
+  // Mark the reservation as loaded with no ceiling so the next stamp
+  // re-reserves from 1, ignoring any reservation file a previous test
+  // wrote into the (per-process temp) workspace.
+  state.reservedSeqCeiling = 0;
+  state.seqReservationLoaded = true;
+  state.firstStampedSeq = 0;
+  state.ring = [];
+  state.totalSizeBytes = 0;
+  state.persistedSeqByConversation.clear();
+}
+
+/**
+ * Simulate a daemon restart: clear all in-memory state and force the
+ * next stamp to reload the persisted seq reservation. Test-only.
+ */
+export function _simulateRestartForTesting(): void {
+  state.nextSeq = 1;
+  state.reservedSeqCeiling = 0;
+  state.seqReservationLoaded = false;
+  state.firstStampedSeq = 0;
   state.ring = [];
   state.totalSizeBytes = 0;
   state.persistedSeqByConversation.clear();
@@ -286,6 +354,71 @@ export function _peekStreamForTesting(): {
 
 // ── Internals ────────────────────────────────────────────────────────
 
+function seqReservationPath(): string {
+  return join(getWorkspaceDir(), "data", "stream-seq.json");
+}
+
+/**
+ * Ensure `state.nextSeq` is covered by the persisted reservation,
+ * loading the reservation file on the first stamp of the process and
+ * extending it by {@link SEQ_RESERVATION_BLOCK} whenever the counter
+ * reaches the ceiling.
+ *
+ * Persistence is best-effort: if the file cannot be read or written
+ * the counter falls back to in-memory-only behavior (the ceiling is
+ * still advanced so the write is retried at most once per block, not
+ * per event), matching the daemon's degraded-mode philosophy.
+ */
+function reserveSeqCapacity(): void {
+  if (!state.seqReservationLoaded) {
+    state.seqReservationLoaded = true;
+    state.reservedSeqCeiling = readReservedCeiling();
+    if (state.reservedSeqCeiling >= state.nextSeq) {
+      state.nextSeq = state.reservedSeqCeiling + 1;
+    }
+  }
+
+  if (state.nextSeq <= state.reservedSeqCeiling) return;
+
+  const ceiling = state.nextSeq + SEQ_RESERVATION_BLOCK - 1;
+  try {
+    const path = seqReservationPath();
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ reservedSeqCeiling: ceiling }));
+    renameSync(tmp, path);
+  } catch {
+    // Degraded mode: keep stamping from memory.
+  }
+  state.reservedSeqCeiling = ceiling;
+}
+
+function readReservedCeiling(): number {
+  try {
+    const parsed: unknown = JSON.parse(
+      readFileSync(seqReservationPath(), "utf8"),
+    );
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      "reservedSeqCeiling" in parsed
+    ) {
+      const ceiling = (parsed as { reservedSeqCeiling: unknown })
+        .reservedSeqCeiling;
+      if (
+        typeof ceiling === "number" &&
+        Number.isFinite(ceiling) &&
+        ceiling > 0
+      ) {
+        return Math.floor(ceiling);
+      }
+    }
+  } catch {
+    // Missing or unreadable file: cold start from seq 1.
+  }
+  return 0;
+}
+
 /**
  * Mirrors the delivery logic in `AssistantEventHub.publish()`. Returns
  * `true` when `subscriber` would have received the entry during live

package/src/runtime/background-job-runner.ts

@@ -67,6 +67,12 @@ export interface RunBackgroundJobOptions {
   trustContext: TrustContext;
   /** LLM call-site identifier — drives provider/model/effort/etc. resolution. */
   callSite: LLMCallSite;
+  /**
+   * Optional ad-hoc inference-profile override (`llm.profiles` key) applied
+   * to every LLM call the job's turn issues. Used by schedules with a pinned
+   * profile; omitted = the call site's default resolution.
+   */
+  overrideProfile?: string;
   /** Hard timeout for `processMessage` in milliseconds. */
   timeoutMs: number;
   /**
@@ -267,6 +273,9 @@ export async function runBackgroundJob(
     const work = processMessage(conversation.id, opts.prompt, {
       trustContext: opts.trustContext,
       callSite: opts.callSite,
+      ...(opts.overrideProfile
+        ? { overrideProfile: opts.overrideProfile }
+        : {}),
     });
     // Absorb late rejections: if the timeout wins the race, `work` keeps
     // running and may eventually reject — swallow so it doesn't surface as

package/src/runtime/channel-approval-types.ts

@@ -92,6 +92,7 @@ export type ApprovalDecisionSource =
   | "whatsapp_button"
   | "slack_button"
   | "slack_reaction"
+  | "vellum_surface"
   | "plain_text";
 
 /** The structured result of a user's approval decision. */

package/src/runtime/guardian-action-message-composer.ts

@@ -8,10 +8,8 @@
  *
  * Follows the same pattern as approval-message-composer.ts.
  */
-import { getLogger } from "../util/logger.js";
 import type {
   ComposeGuardianActionMessageOptions,
-  GuardianActionCopyGenerator,
   GuardianActionMessageContext,
 } from "./message-composer-types.js";
 
@@ -21,21 +19,6 @@ export type {
   GuardianActionMessageScenario,
 } from "./message-composer-types.js";
 
-const log = getLogger("guardian-action-message-composer");
-
-// ---------------------------------------------------------------------------
-// Constants (exported for the daemon-injected generator implementation)
-// ---------------------------------------------------------------------------
-
-export const GUARDIAN_ACTION_COPY_TIMEOUT_MS = 4_000;
-export const GUARDIAN_ACTION_COPY_MAX_TOKENS = 200;
-export const GUARDIAN_ACTION_COPY_SYSTEM_PROMPT =
-  "You are an assistant writing one user-facing message about a guardian action in a voice call scenario. " +
-  "Keep it concise, natural, and conversational. Preserve factual details exactly. " +
-  "These messages are spoken aloud, so use a warm, human tone. " +
-  "Do not mention internal systems, scenario IDs, or technical details. " +
-  "Return plain text only.";
-
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -51,7 +34,6 @@ export const GUARDIAN_ACTION_COPY_SYSTEM_PROMPT =
 export async function composeGuardianActionMessageGenerative(
   context: GuardianActionMessageContext,
   options: ComposeGuardianActionMessageOptions = {},
-  generator?: GuardianActionCopyGenerator,
 ): Promise<string> {
   const fallbackText =
     options.fallbackText?.trim() || getGuardianActionFallbackMessage(context);
@@ -60,45 +42,9 @@ export async function composeGuardianActionMessageGenerative(
     return fallbackText;
   }
 
-  if (generator) {
-    try {
-      const generated = await generator(context, options);
-      if (generated) return generated;
-    } catch (err) {
-      log.warn(
-        { err, scenario: context.scenario },
-        "Failed to generate guardian action copy, using fallback",
-      );
-    }
-  }
-
   return fallbackText;
 }
 
-/** @internal Exported for use by the daemon-injected generator implementation. */
-export function buildGuardianActionGenerationPrompt(
-  context: GuardianActionMessageContext,
-  fallbackText: string,
-  requiredKeywords: string[] | undefined,
-): string {
-  const keywordClause =
-    requiredKeywords && requiredKeywords.length > 0
-      ? `Required words to include (as standalone words): ${requiredKeywords.join(
-          ", ",
-        )}.\n`
-      : "";
-  return [
-    "Rewrite the following guardian action message as a natural, conversational reply.",
-    "These messages are for voice call scenarios and may be spoken aloud.",
-    "Keep the same concrete facts and next-step guidance.",
-    keywordClause,
-    `Context JSON: ${JSON.stringify(context)}`,
-    `Fallback message: ${fallbackText}`,
-  ]
-    .filter(Boolean)
-    .join("\n\n");
-}
-
 /** @internal Exported for use by the daemon-injected generator implementation. */
 export function includesRequiredKeywords(
   text: string,

package/src/runtime/http-server.ts

@@ -7,10 +7,6 @@
 
 import type { ServerWebSocket } from "bun";
 
-import {
-  startGuardianActionSweep,
-  stopGuardianActionSweep,
-} from "../calls/guardian-action-sweep.js";
 import {
   activeMediaStreamSessions,
   MediaStreamCallSession,
@@ -29,7 +25,6 @@ import { isHttpAuthDisabled } from "../config/env.js";
 import { getIsPlatform } from "../config/env-registry.js";
 import { getConfig } from "../config/loader.js";
 import { createApprovalCopyGenerator } from "../daemon/approval-generators.js";
-import { createGuardianActionCopyGenerator } from "../daemon/guardian-action-generators.js";
 import { processMessage } from "../daemon/process-message.js";
 import { createLiveVoiceSession } from "../live-voice/live-voice-session.js";
 import { LiveVoiceSessionManager } from "../live-voice/live-voice-session-manager.js";
@@ -61,11 +56,11 @@ import {
 } from "./middleware/auth.js";
 import { withErrorHandling } from "./middleware/error-handler.js";
 import {
-  apiRateLimiter,
   extractClientIp,
   ipRateLimiter,
   rateLimitHeaders,
   rateLimitResponse,
+  selectAuthenticatedRateLimiter,
 } from "./middleware/rate-limiter.js";
 import { withRequestLogging } from "./middleware/request-logger.js";
 import {
@@ -99,7 +94,6 @@ export { isPrivateAddress } from "./middleware/auth.js";
 
 import type {
   ApprovalCopyGenerator,
-  GuardianActionCopyGenerator,
   RuntimeHttpServerOptions,
 } from "./http-types.js";
 
@@ -162,7 +156,6 @@ export class RuntimeHttpServer {
   private hostname: string;
 
   private readonly approvalCopyGenerator: ApprovalCopyGenerator;
-  private readonly guardianActionCopyGenerator: GuardianActionCopyGenerator;
   private retrySweepTimer: ReturnType<typeof setInterval> | null = null;
   private sweepInProgress = false;
 
@@ -174,7 +167,6 @@ export class RuntimeHttpServer {
     this.hostname = options.hostname ?? DEFAULT_HOSTNAME;
 
     this.approvalCopyGenerator = createApprovalCopyGenerator();
-    this.guardianActionCopyGenerator = createGuardianActionCopyGenerator();
     this.liveVoiceSessionManager = new LiveVoiceSessionManager({
       createSession: (context) => createLiveVoiceSession(context),
     });
@@ -486,9 +478,6 @@ export class RuntimeHttpServer {
     startGuardianExpirySweep(this.approvalCopyGenerator);
     log.info("Guardian approval expiry sweep started");
 
-    startGuardianActionSweep(this.guardianActionCopyGenerator);
-    log.info("Guardian action expiry sweep started");
-
     startCanonicalGuardianExpirySweep();
     log.info("Canonical guardian request expiry sweep started");
 
@@ -498,7 +487,6 @@ export class RuntimeHttpServer {
 
   async stop(): Promise<void> {
     stopGuardianExpirySweep();
-    stopGuardianActionSweep();
     stopCanonicalGuardianExpirySweep();
     stopInferenceProfileSessionReaper();
     if (this.retrySweepTimer) {
@@ -702,7 +690,11 @@ export class RuntimeHttpServer {
     if (!isHttpAuthDisabled()) {
       const clientIp = extractClientIp(req, server);
       const token = extractBearerToken(req);
-      const limiter = token ? apiRateLimiter : ipRateLimiter;
+      // Authenticated loopback clients (desktop app, CLI — anything on the
+      // daemon's own host) get a higher budget than remote clients.
+      const limiter = token
+        ? selectAuthenticatedRateLimiter(clientIp)
+        : ipRateLimiter;
       const limiterKind = token ? "authenticated" : "unauthenticated";
       const result = limiter.check(clientIp, path);
       if (!result.allowed) {

package/src/runtime/http-types.ts

@@ -22,7 +22,6 @@ import type { AssistantEventHub } from "./assistant-event-hub.js";
 export type {
   ApprovalCopyGenerator,
   ComposeApprovalMessageGenerativeOptions,
-  GuardianActionCopyGenerator,
 } from "./message-composer-types.js";
 import type { TrustContext } from "../daemon/trust-context.js";
 

package/src/runtime/message-composer-types.ts

@@ -123,12 +123,3 @@ export interface ComposeGuardianActionMessageOptions {
   maxTokens?: number;
   timeoutMs?: number;
 }
-
-/**
- * Daemon-injected function that generates guardian action copy using a provider.
- * Returns generated text or `null` on failure (caller falls back to deterministic text).
- */
-export type GuardianActionCopyGenerator = (
-  context: GuardianActionMessageContext,
-  options?: ComposeGuardianActionMessageOptions,
-) => Promise<string | null>;

package/src/runtime/middleware/__tests__/rate-limiter.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+
+import { isLoopbackAddress } from "../auth.js";
+import {
+  apiRateLimiter,
+  loopbackApiRateLimiter,
+  selectAuthenticatedRateLimiter,
+} from "../rate-limiter.js";
+
+describe("isLoopbackAddress", () => {
+  test("accepts loopback addresses", () => {
+    expect(isLoopbackAddress("127.0.0.1")).toBe(true);
+    expect(isLoopbackAddress("127.42.0.7")).toBe(true);
+    expect(isLoopbackAddress("::1")).toBe(true);
+    expect(isLoopbackAddress("::ffff:127.0.0.1")).toBe(true);
+  });
+
+  test("rejects private (non-loopback) and public addresses", () => {
+    expect(isLoopbackAddress("10.0.0.1")).toBe(false);
+    expect(isLoopbackAddress("192.168.1.20")).toBe(false);
+    expect(isLoopbackAddress("172.16.0.5")).toBe(false);
+    expect(isLoopbackAddress("169.254.0.1")).toBe(false);
+    expect(isLoopbackAddress("::ffff:10.0.0.1")).toBe(false);
+    expect(isLoopbackAddress("fe80::1")).toBe(false);
+    expect(isLoopbackAddress("fd00::1")).toBe(false);
+    expect(isLoopbackAddress("8.8.8.8")).toBe(false);
+  });
+
+  test("rejects malformed input", () => {
+    expect(isLoopbackAddress("")).toBe(false);
+    expect(isLoopbackAddress("localhost")).toBe(false);
+    expect(isLoopbackAddress("127.0.0")).toBe(false);
+    expect(isLoopbackAddress("127.0.0.999")).toBe(false);
+  });
+});
+
+describe("selectAuthenticatedRateLimiter", () => {
+  test("loopback clients get the higher-budget limiter", () => {
+    expect(selectAuthenticatedRateLimiter("127.0.0.1")).toBe(
+      loopbackApiRateLimiter,
+    );
+    expect(selectAuthenticatedRateLimiter("::1")).toBe(loopbackApiRateLimiter);
+    expect(selectAuthenticatedRateLimiter("::ffff:127.0.0.1")).toBe(
+      loopbackApiRateLimiter,
+    );
+  });
+
+  test("remote and LAN clients get the standard limiter", () => {
+    expect(selectAuthenticatedRateLimiter("192.168.1.20")).toBe(apiRateLimiter);
+    expect(selectAuthenticatedRateLimiter("203.0.113.9")).toBe(apiRateLimiter);
+  });
+
+  test("loopback budget exceeds the standard budget", () => {
+    const loopback = loopbackApiRateLimiter.check(
+      "test-loopback-budget",
+      "/v1/test",
+    );
+    const standard = apiRateLimiter.check("test-standard-budget", "/v1/test");
+    expect(loopback.limit).toBeGreaterThan(standard.limit);
+    expect(loopback.limit).toBe(1200);
+    expect(standard.limit).toBe(300);
+  });
+});

package/src/runtime/middleware/auth.ts

@@ -12,6 +12,32 @@ export function isLoopbackHost(hostname: string): boolean {
   );
 }
 
+/** Unwrap IPv4-mapped IPv6 (e.g. ::ffff:10.0.0.1) to its IPv4 part. */
+function unwrapV4Mapped(addr: string): string {
+  const v4Mapped = addr.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
+  return v4Mapped ? v4Mapped[1] : addr;
+}
+
+/**
+ * Determine whether an IP address string is a loopback address —
+ * 127.0.0.0/8, ::1, or their IPv4-mapped IPv6 forms. Strictly narrower
+ * than {@link isPrivateAddress}: LAN peers (RFC 1918, link-local) are
+ * private but not loopback.
+ */
+export function isLoopbackAddress(addr: string): boolean {
+  const normalized = unwrapV4Mapped(addr);
+
+  if (normalized.includes(".")) {
+    const parts = normalized.split(".").map(Number);
+    if (parts.length !== 4 || parts.some((p) => isNaN(p) || p < 0 || p > 255))
+      return false;
+    // Loopback: 127.0.0.0/8
+    return parts[0] === 127;
+  }
+
+  return normalized.toLowerCase() === "::1";
+}
+
 /**
  * @internal Exported for testing.
  *
@@ -24,9 +50,7 @@ export function isLoopbackHost(hostname: string): boolean {
  *   - IPv4-mapped IPv6 variants of all of the above (::ffff:x.x.x.x)
  */
 export function isPrivateAddress(addr: string): boolean {
-  // Handle IPv4-mapped IPv6 (e.g. ::ffff:10.0.0.1) -- extract the IPv4 part
-  const v4Mapped = addr.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
-  const normalized = v4Mapped ? v4Mapped[1] : addr;
+  const normalized = unwrapV4Mapped(addr);
 
   // IPv4 checks
   if (normalized.includes(".")) {

package/src/runtime/middleware/rate-limiter.ts

@@ -4,7 +4,7 @@
 
 import { getLogger } from "../../util/logger.js";
 import type { HttpErrorResponse } from "../http-errors.js";
-import { isPrivateAddress } from "./auth.js";
+import { isLoopbackAddress, isPrivateAddress } from "./auth.js";
 
 const log = getLogger("rate-limiter");
 
@@ -12,6 +12,14 @@ const DEFAULT_MAX_REQUESTS = 300;
 const DEFAULT_WINDOW_MS = 60_000; // 60 seconds
 const MAX_TRACKED_TOKENS = 10_000;
 
+// Higher budget for authenticated loopback clients. Loopback means the
+// request originated on the daemon's own host (desktop app, CLI, local
+// scripts) — proxied remote traffic resolves to its forwarded client IP
+// instead (see extractClientIp). Local clients legitimately burst far
+// beyond the remote budget: a cold sidebar load at thousands of
+// conversations pages through hundreds of GETs in a few seconds.
+const LOOPBACK_MAX_REQUESTS = 1200;
+
 // Lower limit for unauthenticated (IP-based) requests to reduce abuse surface.
 const DEFAULT_IP_MAX_REQUESTS = 20;
 const DEFAULT_IP_WINDOW_MS = 60_000;
@@ -186,6 +194,15 @@ export function rateLimitResponse(
 /** Singleton rate limiter for authenticated /v1/* requests (per-client-IP). */
 export const apiRateLimiter = new TokenRateLimiter();
 
+/**
+ * Singleton rate limiter for authenticated requests from loopback clients.
+ * Separate instance (not just a higher cap) so local and remote traffic
+ * never share or evict each other's buckets.
+ */
+export const loopbackApiRateLimiter = new TokenRateLimiter(
+  LOOPBACK_MAX_REQUESTS,
+);
+
 /** Singleton rate limiter for unauthenticated requests (per-IP, lower limits). */
 export const ipRateLimiter = new TokenRateLimiter(
   DEFAULT_IP_MAX_REQUESTS,
@@ -193,6 +210,16 @@ export const ipRateLimiter = new TokenRateLimiter(
   MAX_TRACKED_IPS,
 );
 
+/**
+ * Pick the rate limiter for an authenticated request: loopback client IPs
+ * get the higher local budget, everything else gets the standard one.
+ */
+export function selectAuthenticatedRateLimiter(
+  clientIp: string,
+): TokenRateLimiter {
+  return isLoopbackAddress(clientIp) ? loopbackApiRateLimiter : apiRateLimiter;
+}
+
 /**
  * Extract the client IP from a request. Only trusts proxy headers
  * (X-Forwarded-For, X-Real-IP) when the peer IP is loopback or private,

package/src/runtime/migrations/vbundle-builder.ts

@@ -3,7 +3,7 @@
  *
  * A .vbundle is a gzip-compressed tar archive containing:
  * - manifest.json: metadata with schema_version, checksums, and bundle info
- * - workspace/: the entire ~/.vellum/workspace/ directory tree (DB, config,
+ * - workspace/: the entire $VELLUM_WORKSPACE_DIR/ directory tree (DB, config,
  *   skills, prompts, attachments, etc.) — excluding large/regenerable
  *   dirs (embedding-models/, data/qdrant/)
  */
@@ -668,7 +668,7 @@ export interface BuildExportVBundleOptions {
   /** Whether secrets were stripped from the bundle before archiving. */
   secretsRedacted: boolean;
   /**
-   * Absolute path to the workspace directory (~/.vellum/workspace/).
+   * Absolute path to the workspace directory ($VELLUM_WORKSPACE_DIR/).
    * When provided and exists, the entire directory tree is walked and
    * included in the archive under the "workspace/" prefix, skipping
    * large/regenerable dirs (embedding-models/, data/qdrant/).
@@ -679,8 +679,9 @@ export interface BuildExportVBundleOptions {
    * Optional callback to checkpoint the WAL before reading the database file.
    * In WAL mode, committed rows may live in the -wal file and not yet be
    * flushed to the main .db file. Callers should pass a function that runs
-   * PRAGMA wal_checkpoint(FULL) on the live database connection. (Not
-   * TRUNCATE — see assistant/AGENTS.md "SQLite WAL checkpointing".)
+   * PRAGMA wal_checkpoint(FULL) on the live database connection — FULL
+   * flushes committed frames to the .db file without the extra WAL restart
+   * and truncation that TRUNCATE performs.
    * Called before the workspace walk so the DB file is up to date.
    *
    * May return a Promise — `streamExportVBundle` awaits the result so an
@@ -696,7 +697,7 @@ export interface BuildExportVBundleOptions {
 /**
  * Build a .vbundle archive populated with real assistant data.
  *
- * Walks the entire workspace directory (~/.vellum/workspace/) and includes
+ * Walks the entire workspace directory ($VELLUM_WORKSPACE_DIR/) and includes
  * all files in the archive, skipping only large/regenerable directories
  * (embedding-models/, data/qdrant/). Binary files (SQLite DB, attachments)
  * are included.