@vellumai/assistant 0.10.2 → 0.10.3-dev.202606252046.9075fd5

package/src/util/errors.ts

@@ -102,6 +102,17 @@ export class AssistantError extends VellumError {
 export class ProviderError extends AssistantError {
   /** Delay (in ms) suggested by the server's Retry-After header, if present. */
   public readonly retryAfterMs?: number;
+  /** Upstream provider error metadata, parsed from the raw non-2xx body. */
+  public readonly apiErrorCode?: string;
+  public readonly apiErrorType?: string;
+  public readonly apiErrorParam?: string;
+  public readonly requestId?: string;
+  /**
+   * Verbatim upstream non-2xx body (possibly truncated). Persisted so the
+   * inspector's Raw tab can show the actual provider error payload, not just
+   * the extracted fields.
+   */
+  public readonly rawBody?: string;
   /**
    * Tagged daemon-owned abort reason carried over from the AbortSignal that
    * triggered this error. Untyped here to avoid a daemon→util import cycle;
@@ -114,11 +125,25 @@ export class ProviderError extends AssistantError {
     message: string,
     public readonly provider: string,
     public readonly statusCode?: number,
-    options?: { cause?: unknown; retryAfterMs?: number; abortReason?: unknown },
+    options?: {
+      cause?: unknown;
+      retryAfterMs?: number;
+      abortReason?: unknown;
+      apiErrorCode?: string;
+      apiErrorType?: string;
+      apiErrorParam?: string;
+      requestId?: string;
+      rawBody?: string;
+    },
   ) {
     super(message, ErrorCode.PROVIDER_ERROR, options);
     this.name = "ProviderError";
     this.retryAfterMs = options?.retryAfterMs;
+    this.apiErrorCode = options?.apiErrorCode;
+    this.apiErrorType = options?.apiErrorType;
+    this.apiErrorParam = options?.apiErrorParam;
+    this.requestId = options?.requestId;
+    this.rawBody = options?.rawBody;
     this.abortReason = options?.abortReason;
   }
 }

package/src/util/logger.ts

@@ -49,6 +49,15 @@ function logFilePathForDate(dir: string, date: Date): string {
   return join(dir, `${LOG_FILE_PREFIX}${formatDate(date)}${LOG_FILE_SUFFIX}`);
 }
 
+/**
+ * Returns the path to today's log file (`<logsDir>/assistant-YYYY-MM-DD.log`).
+ * Used by callers that need to open the same file the logger writes to, e.g.
+ * the memory worker spawner piping the child's stderr into the log file.
+ */
+export function getCurrentLogFilePath(): string {
+  return logFilePathForDate(getLogsDir(), new Date());
+}
+
 export function pruneOldLogFiles(dir: string, retentionDays: number): number {
   if (!existsSync(dir)) return 0;
 

package/src/util/platform.ts

@@ -242,6 +242,25 @@ export function getEmbedWorkerPidPath(): string {
   return join(getWorkspaceDir(), "embed-worker.pid");
 }
 
+/** Returns the path to the memory-worker PID file ($VELLUM_WORKSPACE_DIR/memory-worker.pid). */
+export function getMemoryWorkerPidPath(): string {
+  return join(getWorkspaceDir(), "memory-worker.pid");
+}
+
+/**
+ * Returns the path to the memory sync-runner marker file
+ * ($VELLUM_WORKSPACE_DIR/memory-sync-runner.pid).
+ *
+ * The daemon's in-process memory-jobs supervisor writes this marker (with its
+ * own PID) while the synchronous in-process runner is actively draining the
+ * queue, and removes it when it stands down for an out-of-process worker. It
+ * lets `assistant memory worker status` report whether the synchronous runner
+ * is still going without an IPC round-trip to the daemon.
+ */
+export function getMemorySyncRunnerMarkerPath(): string {
+  return join(getWorkspaceDir(), "memory-sync-runner.pid");
+}
+
 /**
  * Returns the workspace root for user-facing state.
  *

package/src/util/telemetry-db-path.ts

@@ -0,0 +1,24 @@
+import { join } from "node:path";
+
+import { getDataDir } from "./platform.js";
+
+/**
+ * Path to the dedicated SQLite file that houses telemetry event tables
+ * (starting with `watchdog_events`). It lives in the same `data/db` directory
+ * as the main DB and is opened on its own connection (see `getTelemetryDb()`
+ * in `memory/db-connection.ts`). Splitting telemetry tables into their own
+ * file keeps the main DB — and its WAL — small and lets the two files
+ * VACUUM/checkpoint independently, so a burst of watchdog events can no longer
+ * bloat the main database.
+ *
+ * Kept in its own leaf module rather than alongside `getDbPath()` in
+ * `platform.ts`: `platform.ts` is imported very early and widely, and adding an
+ * export to it that low-level consumers (e.g. `db-connection.ts`) pull in
+ * across the daemon's large, cyclic import graph trips a Bun link-order bug
+ * ("Export named 'getTelemetryDbPath' not found"). Isolating it here keeps
+ * `platform.ts`'s module shape stable — same reasoning as `logs-db-path.ts`
+ * and `memory-db-path.ts`.
+ */
+export function getTelemetryDbPath(): string {
+  return join(getDataDir(), "db", "assistant-telemetry.db");
+}

package/src/workflows/library.test.ts

@@ -37,6 +37,13 @@ function writeWorkflow(file: string, source: string): void {
   writeFileSync(join(dir, file), source, "utf8");
 }
 
+/** Write `<workspace>/workflows/<name>/workflow.ts` (directory-style). */
+function writeDirWorkflow(name: string, source: string): void {
+  const dir = join(workspaceDir, "workflows", name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "workflow.ts"), source, "utf8");
+}
+
 describe("listWorkflows", () => {
   test("returns [] and does not create the dir when none exists", () => {
     expect(listWorkflows()).toEqual([]);
@@ -84,6 +91,51 @@ describe("listWorkflows", () => {
     expect(entries.map((e) => e.name)).toEqual(["real"]);
   });
 
+  test("includes both flat and directory-style workflows", () => {
+    writeWorkflow(
+      "flat.workflow.ts",
+      `export const meta = { name: "flat-wf", description: "flat" };\nreturn 1;`,
+    );
+    writeDirWorkflow(
+      "dir-wf",
+      `export const meta = { name: "dir-wf", description: "dir" };\nreturn 1;`,
+    );
+
+    const entries = listWorkflows().sort((a, b) =>
+      a.name.localeCompare(b.name),
+    );
+    expect(entries.map((e) => e.name)).toEqual(["dir-wf", "flat-wf"]);
+    expect(entries[0]!.path).toContain(join("dir-wf", "workflow.ts"));
+    expect(entries[1]!.path).toContain("flat.workflow.ts");
+  });
+
+  test("ignores a subdir without a workflow.ts and does not recurse deeper", () => {
+    writeWorkflow(
+      "real.workflow.ts",
+      `export const meta = { name: "real", description: "d" };\nreturn 1;`,
+    );
+    // Subdir with no entry-point workflow.ts.
+    mkdirSync(join(workspaceDir, "workflows", "empty-dir"), {
+      recursive: true,
+    });
+    writeFileSync(
+      join(workspaceDir, "workflows", "empty-dir", "notes.ts"),
+      `export const meta = { name: "ignored", description: "d" };`,
+      "utf8",
+    );
+    // A nested workflow.ts one level deeper than supported must not be picked up.
+    mkdirSync(join(workspaceDir, "workflows", "outer", "inner"), {
+      recursive: true,
+    });
+    writeFileSync(
+      join(workspaceDir, "workflows", "outer", "inner", "workflow.ts"),
+      `export const meta = { name: "too-deep", description: "d" };`,
+      "utf8",
+    );
+
+    expect(listWorkflows().map((e) => e.name)).toEqual(["real"]);
+  });
+
   test("skips a file whose meta is computed/non-literal (cannot be statically extracted)", () => {
     writeWorkflow(
       "ok.workflow.ts",
@@ -131,4 +183,92 @@ describe("getWorkflow", () => {
     );
     expect(getWorkflow("ghost")).toBeNull();
   });
+
+  test("resolves a directory-style workflow by meta.name", () => {
+    const source = `export const meta = { name: "dir-digest", description: "d" };\nreturn agent("go");`;
+    writeDirWorkflow("dir-digest", source);
+
+    const resolved = getWorkflow("dir-digest");
+    expect(resolved).not.toBeNull();
+    expect(resolved!.source).toBe(source);
+    expect(resolved!.path).toContain(join("dir-digest", "workflow.ts"));
+  });
+
+  test("resolves a directory-style workflow by directory name when meta.name differs", () => {
+    // meta.name is "canonical" but the dir (and caller's name) is "by-dir".
+    const source = `export const meta = { name: "canonical", description: "d" };\nreturn 1;`;
+    writeDirWorkflow("by-dir", source);
+
+    expect(getWorkflow("by-dir")!.source).toBe(source);
+    // The canonical meta.name also resolves.
+    expect(getWorkflow("canonical")!.source).toBe(source);
+  });
+
+  test("prefers a meta.name match over a base-name match", () => {
+    // Asking for "wanted" should hit the file whose meta.name is "wanted",
+    // not the file whose base name is "wanted" (whose meta.name differs).
+    writeWorkflow(
+      "wanted.workflow.ts",
+      `export const meta = { name: "other", description: "by base name" };\nreturn 1;`,
+    );
+    const metaSource = `export const meta = { name: "wanted", description: "by meta name" };\nreturn 1;`;
+    writeWorkflow("real.workflow.ts", metaSource);
+
+    expect(getWorkflow("wanted")!.source).toBe(metaSource);
+  });
+});
+
+describe("name collisions", () => {
+  test("a directory wins over a same-base-name flat file", () => {
+    writeWorkflow(
+      "foo.workflow.ts",
+      `export const meta = { name: "foo", description: "flat" };\nreturn "FLAT";`,
+    );
+    writeDirWorkflow(
+      "foo",
+      `export const meta = { name: "foo", description: "dir" };\nreturn "DIR";`,
+    );
+
+    const resolved = getWorkflow("foo")!;
+    expect(resolved.source).toContain("DIR");
+    expect(resolved.path.endsWith(join("foo", "workflow.ts"))).toBe(true);
+
+    const foos = listWorkflows().filter((e) => e.name === "foo");
+    expect(foos).toHaveLength(1);
+    expect(foos[0]!.description).toBe("dir");
+  });
+
+  test("the shadowed flat file's own meta.name no longer resolves", () => {
+    writeWorkflow(
+      "bar.workflow.ts",
+      `export const meta = { name: "flat-name", description: "flat" };\nreturn "FLAT";`,
+    );
+    writeDirWorkflow(
+      "bar",
+      `export const meta = { name: "dir-name", description: "dir" };\nreturn "DIR";`,
+    );
+
+    expect(getWorkflow("dir-name")!.source).toContain("DIR");
+    expect(getWorkflow("flat-name")).toBeNull();
+    // Base-name fallback also lands on the directory.
+    expect(getWorkflow("bar")!.source).toContain("DIR");
+    expect(listWorkflows().map((e) => e.name)).toEqual(["dir-name"]);
+  });
+
+  test("listWorkflows dedups a duplicate meta.name across different files", () => {
+    writeWorkflow(
+      "a.workflow.ts",
+      `export const meta = { name: "dup", description: "from-a" };\nreturn "A";`,
+    );
+    writeDirWorkflow(
+      "b",
+      `export const meta = { name: "dup", description: "from-b" };\nreturn "B";`,
+    );
+
+    // One entry; the directory (yielded first) wins, consistent with getWorkflow.
+    const dups = listWorkflows().filter((e) => e.name === "dup");
+    expect(dups).toHaveLength(1);
+    expect(dups[0]!.description).toBe("from-b");
+    expect(getWorkflow("dup")!.source).toContain("B");
+  });
 });

package/src/workflows/library.ts

@@ -2,13 +2,17 @@
  * Saved-workflow LIBRARY — named workflows the assistant can invoke by name and
  * the scheduler can trigger.
  *
- * Saved workflows live at `<workspace>/workflows/*.workflow.ts`. Each file is a
- * normal workflow script: a leading literal `export const meta = { name,
- * description }` followed by the script body. The library only reads the STATIC
- * `meta` (via {@link extractWorkflowMeta}, a pure-literal extractor that never
- * executes the untrusted source — only the QuickJS sandbox may run it) and the
- * raw source. Resolution to an actual run goes through {@link executeWorkflow} /
- * {@link WorkflowRunManager}, which run the source in the sandbox.
+ * Saved workflows live at `<workspace>/workflows/`. The preferred layout is
+ * directory-style `<name>/workflow.ts` (so a workflow and its state can sit in
+ * one folder); flat `<name>.workflow.ts` is still supported but discouraged. On
+ * a base-name collision the directory wins. Each is a normal workflow script: a
+ * leading literal
+ * `export const meta = { name, description }` followed by the script body. The
+ * library only reads the STATIC `meta` (via {@link extractWorkflowMeta}, a
+ * pure-literal extractor that never executes the untrusted source — only the
+ * QuickJS sandbox may run it) and the raw source. Resolution to an actual run
+ * goes through {@link executeWorkflow} / {@link WorkflowRunManager}, which run
+ * the source in the sandbox.
  *
  * The directory is read lazily and is NOT created eagerly: if it does not exist,
  * {@link listWorkflows} returns `[]` and {@link getWorkflow} returns `null`.
@@ -19,7 +23,7 @@ import { join } from "node:path";
 
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceDir } from "../util/platform.js";
-import { extractWorkflowMeta } from "./engine.js";
+import { extractWorkflowMeta, type WorkflowMeta } from "./engine.js";
 
 const log = getLogger("workflow-library");
 
@@ -49,31 +53,66 @@ function workflowsDir(): string {
   return join(getWorkspaceDir(), "workflows");
 }
 
+/** Filename of the entry-point script inside a directory-style workflow. */
+const DIRECTORY_ENTRY = "workflow.ts";
+
 /** The filename (sans `.workflow.ts`) for `<workspace>/workflows/<base>.workflow.ts`. */
 function fileBaseName(file: string): string {
   return file.slice(0, -WORKFLOW_SUFFIX.length);
 }
 
-/** A `*.workflow.ts` file read off disk, before meta extraction. */
+/** A saved workflow read off disk, before meta extraction. */
 interface RawWorkflowFile {
-  file: string;
+  /** Base identity for the filename/dir fallback match (see {@link getWorkflow}). */
+  baseName: string;
   path: string;
   source: string;
 }
 
 /**
- * Yield every readable `*.workflow.ts` file in the workflows directory (each read
- * once). Returns nothing if the directory does not exist — it is never created.
- * An unreadable file is skipped with a logged warning.
+ * Yield every readable saved workflow in a STABLE order (the raw filesystem
+ * listing order is not guaranteed, so callers that take "the first match" stay
+ * deterministic). Directory-style `<name>/workflow.ts` is yielded first and
+ * WINS: a flat `<name>.workflow.ts` with the same base name is shadowed (skipped
+ * with a warning). Yields nothing if the directory does not exist — it is never
+ * created. An unreadable entry is skipped with a logged warning.
  */
 function* readWorkflowFiles(): Generator<RawWorkflowFile> {
   const dir = workflowsDir();
   if (!existsSync(dir)) return;
-  for (const file of readdirSync(dir)) {
-    if (!file.endsWith(WORKFLOW_SUFFIX)) continue;
-    const path = join(dir, file);
+  const entries = readdirSync(dir).sort();
+  const seen = new Set<string>();
+
+  // Directory-style first, so it wins over a same-base-name flat file.
+  for (const entry of entries) {
+    if (entry.endsWith(WORKFLOW_SUFFIX)) continue;
+    const path = join(dir, entry, DIRECTORY_ENTRY);
+    if (!existsSync(path)) continue;
+    try {
+      const source = readFileSync(path, "utf8");
+      seen.add(entry);
+      yield { baseName: entry, path, source };
+    } catch (err) {
+      log.warn({ err, path }, "Failed to read saved workflow; skipping");
+    }
+  }
+
+  // Flat files second; skip any shadowed by a directory of the same base name.
+  for (const entry of entries) {
+    if (!entry.endsWith(WORKFLOW_SUFFIX)) continue;
+    const baseName = fileBaseName(entry);
+    const path = join(dir, entry);
+    if (seen.has(baseName)) {
+      log.warn(
+        { path },
+        `Flat workflow "${entry}" is shadowed by directory "${baseName}/"; skipping`,
+      );
+      continue;
+    }
     try {
-      yield { file, path, source: readFileSync(path, "utf8") };
+      const source = readFileSync(path, "utf8");
+      seen.add(baseName);
+      yield { baseName, path, source };
     } catch (err) {
       log.warn({ err, path }, "Failed to read saved workflow; skipping");
     }
@@ -81,42 +120,57 @@ function* readWorkflowFiles(): Generator<RawWorkflowFile> {
 }
 
 /**
- * List every saved workflow with a statically-extractable `meta`. A file whose
- * `meta` cannot be statically extracted (computed/missing/malformed) is SKIPPED
- * with a logged warning rather than failing the whole listing.
+ * List every saved workflow with a statically-extractable `meta`, deduplicated
+ * by `meta.name` — the first in {@link readWorkflowFiles}' stable order wins, a
+ * later duplicate is skipped with a warning (matching {@link getWorkflow}'s
+ * winner). A file whose `meta` cannot be statically extracted is skipped with a
+ * warning rather than failing the whole listing.
  */
 export function listWorkflows(): SavedWorkflowEntry[] {
   const entries: SavedWorkflowEntry[] = [];
+  const seenNames = new Set<string>();
   for (const { path, source } of readWorkflowFiles()) {
+    let meta: WorkflowMeta;
     try {
-      const meta = extractWorkflowMeta(source);
-      entries.push({ name: meta.name, description: meta.description, path });
+      meta = extractWorkflowMeta(source);
     } catch (err) {
       log.warn(
         { err, path },
         "Saved workflow has no statically-extractable meta; skipping",
       );
+      continue;
+    }
+    if (seenNames.has(meta.name)) {
+      log.warn(
+        { path, name: meta.name },
+        `Duplicate workflow name "${meta.name}"; skipping shadowed entry`,
+      );
+      continue;
     }
+    seenNames.add(meta.name);
+    entries.push({ name: meta.name, description: meta.description, path });
   }
   return entries;
 }
 
 /**
- * Resolve a saved workflow by name. Matches against the workflow's `meta.name`
- * first, then falls back to the filename base (`<base>.workflow.ts`). Returns the
- * source + path, or `null` if no saved workflow matches.
+ * Resolve a saved workflow by name, deterministically — {@link readWorkflowFiles}
+ * yields in a stable order with directory-over-flat precedence, so "the first
+ * match" is well-defined. Matches `meta.name` first (the canonical identity),
+ * then falls back to the base name (directory or flat-file). Returns the source
+ * + path, or `null` if nothing matches.
  */
 export function getWorkflow(name: string): SavedWorkflowSource | null {
   let fileMatch: SavedWorkflowSource | null = null;
-  for (const { file, path, source } of readWorkflowFiles()) {
+  for (const { baseName, path, source } of readWorkflowFiles()) {
     // Prefer a `meta.name` match — it is the canonical identity.
     try {
       if (extractWorkflowMeta(source).name === name) return { source, path };
     } catch {
       // Fall through: a file with non-extractable meta can still match by name.
     }
-    // Remember the first filename-base match as a fallback.
-    if (fileMatch === null && fileBaseName(file) === name) {
+    // Remember the first base-name match as a fallback.
+    if (fileMatch === null && baseName === name) {
       fileMatch = { source, path };
     }
   }

package/src/workspace/migrations/017-seed-persona-dirs.ts

@@ -8,11 +8,6 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 
-import { desc, eq } from "drizzle-orm";
-
-import { generateUserFileSlug } from "../../contacts/contact-store.js";
-import { getDb } from "../../memory/db-connection.js";
-import { contacts } from "../../memory/schema/contacts.js";
 import type { WorkspaceMigration } from "./types.js";
 
 // ── Inlined helpers ───────────────────────────────────────────────
@@ -122,35 +117,9 @@ export const seedPersonaDirsMigration: WorkspaceMigration = {
     // template from disk, since migration 031 deletes that template file.
     if (content === LEGACY_USER_MD_TEMPLATE_STRIPPED) return;
 
-    // Determine destination filename based on guardian contact
-    let destFilename = "guardian.md";
-    try {
-      const db = getDb();
-      const guardian = db
-        .select()
-        .from(contacts)
-        .where(eq(contacts.role, "guardian"))
-        .orderBy(desc(contacts.createdAt))
-        .limit(1)
-        .get();
-
-      if (guardian) {
-        if (guardian.userFile) {
-          destFilename = guardian.userFile;
-        } else {
-          const slug = generateUserFileSlug(guardian.displayName);
-          db.update(contacts)
-            .set({ userFile: slug })
-            .where(eq(contacts.id, guardian.id))
-            .run();
-          destFilename = slug;
-        }
-      }
-    } catch {
-      // DB might not be initialized yet — fall back to guardian.md
-    }
-
-    const destPath = join(workspaceDir, "users", destFilename);
+    // Seed the canonical `users/guardian.md` — the runtime persona resolver
+    // falls back to this name, so no assistant-DB lookup is needed.
+    const destPath = join(workspaceDir, "users", "guardian.md");
     if (!existsSync(destPath)) {
       copyFileSync(userMdPath, destPath);
     }

package/src/workspace/migrations/019-scope-journal-to-guardian.ts

@@ -8,10 +8,6 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 
-import { desc, eq } from "drizzle-orm";
-
-import { getDb } from "../../memory/db-connection.js";
-import { contacts } from "../../memory/schema/contacts.js";
 import type { WorkspaceMigration } from "./types.js";
 
 export const scopeJournalToGuardianMigration: WorkspaceMigration = {
@@ -40,26 +36,9 @@ export const scopeJournalToGuardianMigration: WorkspaceMigration = {
     });
     if (mdFiles.length === 0) return;
 
-    // Resolve guardian user slug (same pattern as 017-seed-persona-dirs)
-    let slug = "guardian";
-    try {
-      const db = getDb();
-      const guardian = db
-        .select()
-        .from(contacts)
-        .where(eq(contacts.role, "guardian"))
-        .orderBy(desc(contacts.createdAt))
-        .limit(1)
-        .get();
-      if (guardian?.userFile) {
-        slug = guardian.userFile.replace(/\.md$/, "");
-      }
-    } catch {
-      // DB not ready — use fallback "guardian"
-    }
-
-    // Create per-user directory and move files (renameSync preserves birthtimes)
-    const destDir = join(journalDir, slug);
+    // Scope under the canonical `guardian` slug — the runtime resolver falls
+    // back to it, so no assistant-DB lookup is needed.
+    const destDir = join(journalDir, "guardian");
     mkdirSync(destDir, { recursive: true });
     for (const f of mdFiles) {
       const src = join(journalDir, f);