@vellumai/assistant 0.7.1 → 0.7.2

package/src/tools/tool-approval-handler.ts

@@ -292,11 +292,7 @@ export class ToolApprovalHandler {
       executionTarget,
     );
 
-    if (
-      isUntrustedTrustClass(context.trustClass) &&
-      guardianApprovalRequired &&
-      context.trustClass !== "trusted_contact"
-    ) {
+    if (isUntrustedTrustClass(context.trustClass) && guardianApprovalRequired) {
       const inputDigest = computeToolApprovalDigest(name, input);
       needsGrantConsumption = true;
       deferredConsumeParams = {

package/src/tools/types.ts

@@ -138,6 +138,10 @@ export interface ToolExecutedEvent {
   riskLevel: string;
   /** ID of the trust rule that matched this invocation (if any). */
   matchedTrustRuleId?: string;
+  /** How the approval decision was reached. Copied from PermissionDecision for analytics consumers. */
+  approvalMode?: string;
+  /** Why the approval decision was reached (stable enum). Copied from PermissionDecision for analytics consumers. */
+  approvalReason?: string;
   decision: string;
   durationMs: number;
   result: ToolExecutionResult;

package/src/usage/pricing.ts

@@ -13,7 +13,7 @@ import type {
 
 const log = getLogger("usage-pricing");
 
-export function normalizeTokenCount(value: number | null | undefined): number {
+function normalizeTokenCount(value: number | null | undefined): number {
   if (typeof value !== "number" || !Number.isFinite(value)) return 0;
   return Math.max(value, 0);
 }

package/src/workspace/hatched-date.ts

@@ -0,0 +1,86 @@
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { getDataDir } from "../util/platform.js";
+
+const HATCHED_SIDECAR_FILENAME = "hatched.json";
+
+export function getHatchedSidecarPath(): string {
+  return join(getDataDir(), HATCHED_SIDECAR_FILENAME);
+}
+
+function normalizeHatchedAt(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+
+  const parsedTime = Date.parse(value);
+  if (isNaN(parsedTime) || parsedTime <= 0) return undefined;
+
+  return new Date(parsedTime).toISOString();
+}
+
+export function readHatchedAtSidecar(): string | undefined {
+  try {
+    const parsed = JSON.parse(
+      readFileSync(getHatchedSidecarPath(), "utf-8"),
+    ) as { hatchedAt?: unknown };
+    return normalizeHatchedAt(parsed.hatchedAt);
+  } catch {
+    return undefined;
+  }
+}
+
+export function writeHatchedAtSidecar(hatchedAt: string): void {
+  const normalized = normalizeHatchedAt(hatchedAt);
+  if (!normalized) return;
+
+  try {
+    mkdirSync(getDataDir(), { recursive: true });
+    writeFileSync(
+      getHatchedSidecarPath(),
+      JSON.stringify({ hatchedAt: normalized }, null, 2),
+      "utf-8",
+    );
+  } catch {
+    // Best-effort stability; callers still return a valid timestamp.
+  }
+}
+
+export function selectHatchedAtFromStats(stats: {
+  birthtime: Date;
+  mtime: Date;
+}): Date | undefined {
+  const candidates = [stats.birthtime, stats.mtime];
+  return candidates.find((candidate) => candidate.getTime() > 0);
+}
+
+function readIdentityFileHatchedAt(identityPath: string): string | undefined {
+  try {
+    return selectHatchedAtFromStats(statSync(identityPath))?.toISOString();
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveHatchedAtReadOnly(
+  identityPath: string,
+  now: Date = new Date(),
+): string {
+  return (
+    readHatchedAtSidecar() ??
+    readIdentityFileHatchedAt(identityPath) ??
+    now.toISOString()
+  );
+}
+
+export function resolveAndPersistHatchedAt(
+  identityPath: string,
+  now: Date = new Date(),
+): string {
+  const sidecarHatchedAt = readHatchedAtSidecar();
+  if (sidecarHatchedAt) return sidecarHatchedAt;
+
+  const hatchedAt =
+    readIdentityFileHatchedAt(identityPath) ?? now.toISOString();
+  writeHatchedAtSidecar(hatchedAt);
+  return hatchedAt;
+}

package/src/workspace/migrations/003-seed-device-id.ts

@@ -45,7 +45,7 @@ export const seedDeviceIdMigration: WorkspaceMigration = {
 
     // b. Read the lockfile to find an existing installationId.
     //    The lockfile is always under the user's home directory, never under
-    //    BASE_DATA_DIR. Check both the current and legacy filenames.
+    //    Check both the current and legacy filenames.
     const home = homedir();
     const lockCandidates = [
       join(home, ".vellum.lock.json"),

package/src/workspace/migrations/006-services-config.ts

@@ -37,8 +37,9 @@ export const servicesConfigMigration: WorkspaceMigration = {
 
     // Skip if no legacy fields remain — either already migrated or a fresh install
     // where schema defaults are correct. We check for legacy fields instead of
-    // services existence because backfillConfigDefaults may have written a default
-    // services object before migrations run.
+    // services existence because legacy daemons (before defaults were applied
+    // only in-memory) may have written a default services object to disk
+    // before migrations run.
     const hasLegacyFields =
       "provider" in config ||
       "model" in config ||
@@ -46,7 +47,8 @@ export const servicesConfigMigration: WorkspaceMigration = {
       "webSearchProvider" in config;
     if (!hasLegacyFields) return;
 
-    // Start from existing services (may have been backfilled by loadConfig defaults)
+    // Start from existing services (legacy daemons may have written a
+    // schema-default services object to disk before this migration runs)
     // so we don't discard any non-default values already written there.
     const existingServices =
       config.services != null &&
@@ -96,8 +98,9 @@ export const servicesConfigMigration: WorkspaceMigration = {
     // Legacy top-level fields (provider, model) are the user's actual
     // configuration from before the services structure existed. If they're
     // present as strings they take precedence over any `existingServices`
-    // values, which are just defaults written by backfillConfigDefaults().
-    // The spread preserves any extra keys that future backfills may add.
+    // values, which on legacy daemons may just be schema defaults that an
+    // older loader wrote to disk. The spread preserves any extra keys that
+    // legacy daemons may have written alongside.
     services.inference = {
       ...(existingServices.inference ?? {}),
       mode: inferenceMode,

package/src/workspace/migrations/016-extract-feature-flags-to-protected.ts

@@ -7,16 +7,10 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
 import type { WorkspaceMigration } from "./types.js";
-
-/** Inlined from platform.ts to satisfy migration self-containment rule (AGENTS.md). */
-function getRootDir(): string {
-  const base = process.env.BASE_DATA_DIR?.trim() || homedir();
-  return join(base, ".vellum");
-}
+import { getVellumRoot } from "./utils.js";
 
 export const extractFeatureFlagsToProtectedMigration: WorkspaceMigration = {
   id: "016-extract-feature-flags-to-protected",
@@ -26,7 +20,7 @@ export const extractFeatureFlagsToProtectedMigration: WorkspaceMigration = {
   down(workspaceDir: string): void {
     // Reverse: read feature flags from protected directory and write them
     // back to config.json as assistantFeatureFlagValues.
-    const protectedDir = join(getRootDir(), "protected");
+    const protectedDir = join(getVellumRoot(), "protected");
     const featureFlagsPath = join(protectedDir, "feature-flags.json");
 
     if (!existsSync(featureFlagsPath)) return;
@@ -111,7 +105,7 @@ export const extractFeatureFlagsToProtectedMigration: WorkspaceMigration = {
     }
 
     // Write feature flags to protected directory
-    const protectedDir = join(getRootDir(), "protected");
+    const protectedDir = join(getVellumRoot(), "protected");
     mkdirSync(protectedDir, { recursive: true });
 
     const featureFlagsPath = join(protectedDir, "feature-flags.json");

package/src/workspace/migrations/021-move-signals-to-workspace.ts

@@ -1,7 +1,7 @@
 /**
  * Workspace migration 021: Move signals directory from root to workspace.
  *
- * Previously, `~/.vellum/signals/` lived directly under getRootDir(). This
+ * Previously, `~/.vellum/signals/` lived directly under the Vellum root. This
  * migration moves any existing signal files into `~/.vellum/workspace/signals/`
  * so that getSignalsDir() resolves correctly under the workspace.
  *
@@ -13,23 +13,17 @@
  */
 
 import { existsSync, mkdirSync, readdirSync, renameSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
 import type { WorkspaceMigration } from "./types.js";
-
-/** Inlined from platform.ts to satisfy migration self-containment rule (AGENTS.md). */
-function getRootDir(): string {
-  const base = process.env.BASE_DATA_DIR?.trim() || homedir();
-  return join(base, ".vellum");
-}
+import { getVellumRoot } from "./utils.js";
 
 export const moveSignalsToWorkspaceMigration: WorkspaceMigration = {
   id: "021-move-signals-to-workspace",
   description: "Move signals directory from root to workspace",
 
   run(workspaceDir: string): void {
-    const oldSignalsDir = join(getRootDir(), "signals");
+    const oldSignalsDir = join(getVellumRoot(), "signals");
     const newSignalsDir = join(workspaceDir, "signals");
 
     mkdirSync(newSignalsDir, { recursive: true });
@@ -56,7 +50,7 @@ export const moveSignalsToWorkspaceMigration: WorkspaceMigration = {
   },
 
   down(workspaceDir: string): void {
-    const oldSignalsDir = join(getRootDir(), "signals");
+    const oldSignalsDir = join(getVellumRoot(), "signals");
     const newSignalsDir = join(workspaceDir, "signals");
 
     mkdirSync(oldSignalsDir, { recursive: true });

package/src/workspace/migrations/022-move-hooks-to-workspace.ts

@@ -1,7 +1,7 @@
 /**
  * Workspace migration 022: Move hooks directory from root to workspace.
  *
- * Previously, `~/.vellum/hooks/` lived directly under getRootDir(). This
+ * Previously, `~/.vellum/hooks/` lived directly under the Vellum root. This
  * migration moves existing hook directories and files into
  * `~/.vellum/workspace/hooks/` so that getWorkspaceHooksDir() resolves
  * correctly under the workspace.
@@ -19,23 +19,17 @@ import {
   renameSync,
   rmSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
 import type { WorkspaceMigration } from "./types.js";
-
-/** Inlined from platform.ts to satisfy migration self-containment rule (AGENTS.md). */
-function getRootDir(): string {
-  const base = process.env.BASE_DATA_DIR?.trim() || homedir();
-  return join(base, ".vellum");
-}
+import { getVellumRoot } from "./utils.js";
 
 export const moveHooksToWorkspaceMigration: WorkspaceMigration = {
   id: "022-move-hooks-to-workspace",
   description: "Move hooks directory from root to workspace",
 
   run(workspaceDir: string): void {
-    const oldHooksDir = join(getRootDir(), "hooks");
+    const oldHooksDir = join(getVellumRoot(), "hooks");
     const newHooksDir = join(workspaceDir, "hooks");
 
     mkdirSync(newHooksDir, { recursive: true });
@@ -65,7 +59,7 @@ export const moveHooksToWorkspaceMigration: WorkspaceMigration = {
   },
 
   down(workspaceDir: string): void {
-    const oldHooksDir = join(getRootDir(), "hooks");
+    const oldHooksDir = join(getVellumRoot(), "hooks");
     const newHooksDir = join(workspaceDir, "hooks");
 
     mkdirSync(oldHooksDir, { recursive: true });

package/src/workspace/migrations/023-move-config-files-to-workspace.ts

@@ -2,23 +2,16 @@
  * Workspace migration 023: Move config/state JSON files from root to workspace.
  *
  * Previously, dictation-profiles.json, email-guardrails.json, and
- * active-call-leases.json lived directly under getRootDir() (~/.vellum/).
+ * active-call-leases.json lived directly under the Vellum root (~/.vellum/).
  * This migration moves them into the workspace directory so they follow
  * the workspace convention for organizational consistency.
  */
 
 import { existsSync, renameSync, unlinkSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
 import type { WorkspaceMigration } from "./types.js";
-
-/** Inlined from platform.ts to satisfy migration self-containment rule (AGENTS.md). */
-function getRootDir(): string {
-  const base = process.env.BASE_DATA_DIR?.trim() || homedir();
-  return join(base, ".vellum");
-}
-
+import { getVellumRoot } from "./utils.js";
 /** Files to move from root → workspace. */
 const CONFIG_FILES = [
   "dictation-profiles.json",
@@ -32,7 +25,7 @@ export const moveConfigFilesToWorkspaceMigration: WorkspaceMigration = {
     "Move dictation-profiles, email-guardrails, and active-call-leases from root to workspace",
 
   run(workspaceDir: string): void {
-    const rootDir = getRootDir();
+    const rootDir = getVellumRoot();
 
     for (const file of CONFIG_FILES) {
       const oldPath = join(rootDir, file);
@@ -60,7 +53,7 @@ export const moveConfigFilesToWorkspaceMigration: WorkspaceMigration = {
   },
 
   down(workspaceDir: string): void {
-    const rootDir = getRootDir();
+    const rootDir = getVellumRoot();
 
     for (const file of CONFIG_FILES) {
       const newPath = join(workspaceDir, file);

package/src/workspace/migrations/024-move-runtime-files-to-workspace.ts

@@ -25,17 +25,10 @@ import {
   renameSync,
   unlinkSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
 import type { WorkspaceMigration } from "./types.js";
-
-/** Inlined from platform.ts to satisfy migration self-containment rule (AGENTS.md). */
-function getRootDir(): string {
-  const base = process.env.BASE_DATA_DIR?.trim() || homedir();
-  return join(base, ".vellum");
-}
-
+import { getVellumRoot } from "./utils.js";
 /** Individual files to move from root → workspace (with optional subdirectory). */
 const FILE_MOVES: Array<{ name: string; subdir?: string }> = [
   { name: "daemon-stderr.log", subdir: "logs" },
@@ -93,7 +86,7 @@ export const moveRuntimeFilesToWorkspaceMigration: WorkspaceMigration = {
     "Move daemon-stderr.log, daemon-startup.lock, embed-worker.pid, external/, and bin/ from root to workspace",
 
   run(workspaceDir: string): void {
-    const rootDir = getRootDir();
+    const rootDir = getVellumRoot();
 
     // Move individual files
     for (const { name, subdir } of FILE_MOVES) {
@@ -110,7 +103,7 @@ export const moveRuntimeFilesToWorkspaceMigration: WorkspaceMigration = {
   },
 
   down(workspaceDir: string): void {
-    const rootDir = getRootDir();
+    const rootDir = getVellumRoot();
 
     // Move individual files back
     for (const { name, subdir } of FILE_MOVES) {

package/src/workspace/migrations/040-seed-latency-callsite-defaults.ts

@@ -22,8 +22,9 @@ import type { WorkspaceMigration } from "./types.js";
  *   2. **Fresh install** (config.json absent): write a minimal starter
  *      config with just the callSite seeds, using the default provider
  *      (anthropic — same as the schema default). `loadConfig()` runs
- *      after migrations and backfills the remaining schema defaults via
- *      `deepMergeMissing`, which preserves our seeded callSites.
+ *      after migrations and applies schema defaults only to the
+ *      in-memory config (disk is left untouched), so our seeded
+ *      callSites are preserved verbatim.
  *
  * Without the fresh-install branch, new users permanently fall through
  * to `llm.default` (opus + max effort) because `LLMSchema.callSites`

package/src/workspace/migrations/050-seed-main-agent-opus-callsite.ts

@@ -12,7 +12,8 @@ import type { WorkspaceMigration } from "./types.js";
  *      `llm.callSites` without overwriting a user-defined override.
  *   2. **Fresh install** (config.json absent): write a minimal starter
  *      config with just this seed. `loadConfig()` runs after migrations
- *      and backfills the remaining schema defaults via `deepMergeMissing`.
+ *      and applies schema defaults to the in-memory config without
+ *      rewriting disk, so the seeded callSite is preserved as-is.
  *
  * Applied only when:
  *   - the resolved provider is Anthropic (other providers own their

package/src/workspace/migrations/059-move-pid-to-workspace.ts

@@ -7,22 +7,17 @@
  */
 
 import { existsSync, renameSync, unlinkSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
 import type { WorkspaceMigration } from "./types.js";
-
-function getRootDir(): string {
-  const base = process.env.BASE_DATA_DIR?.trim() || homedir();
-  return join(base, ".vellum");
-}
+import { getVellumRoot } from "./utils.js";
 
 export const movePidToWorkspaceMigration: WorkspaceMigration = {
   id: "059-move-pid-to-workspace",
   description: "Move vellum.pid from root to workspace",
 
   run(workspaceDir: string): void {
-    const oldPath = join(getRootDir(), "vellum.pid");
+    const oldPath = join(getVellumRoot(), "vellum.pid");
     const newPath = join(workspaceDir, "vellum.pid");
     if (!existsSync(oldPath)) return;
     if (existsSync(newPath)) {
@@ -37,7 +32,7 @@ export const movePidToWorkspaceMigration: WorkspaceMigration = {
   },
 
   down(workspaceDir: string): void {
-    const oldPath = join(getRootDir(), "vellum.pid");
+    const oldPath = join(getVellumRoot(), "vellum.pid");
     const newPath = join(workspaceDir, "vellum.pid");
     if (!existsSync(newPath)) return;
     if (existsSync(oldPath)) {

package/src/workspace/migrations/061-move-backup-key-to-workspace.ts

@@ -11,22 +11,17 @@
  */
 
 import { copyFileSync, existsSync, unlinkSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
 import type { WorkspaceMigration } from "./types.js";
-
-function getRootDir(): string {
-  const base = process.env.BASE_DATA_DIR?.trim() || homedir();
-  return join(base, ".vellum");
-}
+import { getVellumRoot } from "./utils.js";
 
 export const moveBackupKeyToWorkspaceMigration: WorkspaceMigration = {
   id: "061-move-backup-key-to-workspace",
   description: "Move backup.key from protected/ to workspace",
 
   run(workspaceDir: string): void {
-    const oldPath = join(getRootDir(), "protected", "backup.key");
+    const oldPath = join(getVellumRoot(), "protected", "backup.key");
     const newPath = join(workspaceDir, ".backup.key");
     if (!existsSync(oldPath)) return;
     if (existsSync(newPath)) {
@@ -42,7 +37,7 @@ export const moveBackupKeyToWorkspaceMigration: WorkspaceMigration = {
   },
 
   down(workspaceDir: string): void {
-    const oldPath = join(getRootDir(), "protected", "backup.key");
+    const oldPath = join(getVellumRoot(), "protected", "backup.key");
     const newPath = join(workspaceDir, ".backup.key");
     if (!existsSync(newPath)) return;
     if (existsSync(oldPath)) {

package/src/workspace/migrations/AGENTS.md

@@ -6,6 +6,6 @@ Each migration file must be **fully self-contained**. All helper functions, cons
 
 - **No external exports.** Migration files must not export anything other than the single `WorkspaceMigration` object. Other code must never import from a migration file.
 - **Duplicate rather than share.** If two migrations need the same helper, duplicate it in both files. Migrations are write-once code — they run once per assistant and are never modified after release. Duplication is preferable to coupling.
-- **Allowed imports:** `./types.js` (for the `WorkspaceMigration` interface), `../../util/logger.js` (for structured logging), and Node/Bun runtime built-ins (`node:fs`, `node:path`, `node:crypto`, `bun:sqlite`, etc.). All other dependencies — both project-internal modules and third-party npm packages — must be inlined. Do not import from shared modules like `../../memory/` or `../../config/`, and do not add npm dependencies.
+- **Allowed imports:** `./types.js` (for the `WorkspaceMigration` interface), `./utils.js` (for shared path-resolution helpers like `getVellumRoot()`), `../../util/logger.js` (for structured logging), and Node/Bun runtime built-ins (`node:fs`, `node:path`, `node:crypto`, `bun:sqlite`, etc.). All other dependencies — both project-internal modules and third-party npm packages — must be inlined. Do not import from shared modules like `../../memory/` or `../../config/`, and do not add npm dependencies.
 - **Graceful on all platforms.** Migrations run on macOS, Linux, and in Docker. Platform-specific operations must no-op gracefully on unsupported platforms — never throw.
 - **Idempotent.** Migrations must be safe to re-run if interrupted. The runner checkpoints state as `"started"` before execution and `"completed"` after, so a crash mid-migration triggers a re-run on next startup.

package/src/workspace/migrations/migrate-to-workspace-volume.ts

@@ -2,7 +2,7 @@
  * Workspace migration: Migrate workspace data from /data to /workspace volume.
  *
  * In the old Docker volume layout, workspace data lived at
- * `$BASE_DATA_DIR/.vellum/workspace`. In the new layout, VELLUM_WORKSPACE_DIR points
+ * `<vellumRoot>/workspace`. In the new layout, VELLUM_WORKSPACE_DIR points
  * to a dedicated volume (e.g. `/workspace`). On first boot with the new layout,
  * this migration copies existing workspace data from the old location to the
  * new volume so nothing is lost.
@@ -24,6 +24,7 @@ import {
 import { join } from "node:path";
 
 import type { WorkspaceMigration } from "./types.js";
+import { getVellumRoot } from "./utils.js";
 
 const SENTINEL_FILENAME = ".workspace-volume-migrated";
 
@@ -68,15 +69,8 @@ export const migrateToWorkspaceVolumeMigration: WorkspaceMigration = {
       return;
     }
 
-    // Resolve the old workspace location: $BASE_DATA_DIR/.vellum/workspace
-    const baseDataDir = process.env.BASE_DATA_DIR?.trim() || undefined;
-    if (!baseDataDir) {
-      // No BASE_DATA_DIR means there's no old location to migrate from
-      writeSentinel(sentinelPath);
-      return;
-    }
-
-    const oldWorkspaceDir = join(baseDataDir, ".vellum", "workspace");
+    // Resolve the old workspace location: <vellumRoot>/workspace
+    const oldWorkspaceDir = join(getVellumRoot(), "workspace");
 
     // If the old workspace doesn't exist or is empty, nothing to migrate
     if (!existsSync(oldWorkspaceDir)) {

package/src/workspace/migrations/utils.ts

@@ -0,0 +1,21 @@
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * Resolve the legacy Vellum root directory (~/.vellum).
+ *
+ * Resolution order:
+ * 1. Parent of VELLUM_WORKSPACE_DIR — e.g. /data/.vellum/workspace → /data/.vellum
+ * 2. If that parent is "/" (workspace at top level, e.g. /workspace), fall back
+ *    to homedir()/.vellum
+ *
+ * This replaces the old inlined `getRootDir()` pattern used by individual migrations.
+ */
+export function getVellumRoot(): string {
+  const workspaceDir = process.env.VELLUM_WORKSPACE_DIR?.trim();
+  if (workspaceDir) {
+    const parent = dirname(workspaceDir);
+    if (parent !== "/") return parent;
+  }
+  return join(homedir(), ".vellum");
+}