@vellumai/assistant 0.5.16 → 0.6.1

package/src/filing/filing-service.ts

@@ -0,0 +1,228 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { getConfig } from "../config/loader.js";
+import type { Speed } from "../config/schemas/inference.js";
+import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
+import { getLogger } from "../util/logger.js";
+import { getWorkspaceDir } from "../util/platform.js";
+import { stripCommentLines } from "../util/strip-comment-lines.js";
+
+const log = getLogger("filing-service");
+
+const FILING_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
+
+const FILING_PROMPT_TEMPLATE = `You are running a periodic knowledge base filing job. This is a background maintenance task.
+
+## Part 1: File the buffer
+
+Read \`pkb/buffer.md\`. For each item in the buffer:
+1. Determine which topic file it belongs in. Check \`pkb/INDEX.md\` to see what topic files exist.
+2. Read the target topic file, then append or integrate the new fact.
+3. If the fact is important enough to always be in context, add it to \`pkb/essentials.md\` instead.
+4. If the fact is a commitment, follow-up, or active project, add it to \`pkb/threads.md\`.
+5. If no existing topic file fits, create a new one and update \`pkb/INDEX.md\`.
+
+After all items are filed, clear the processed items from \`pkb/buffer.md\` (leave the file empty, don't delete it).
+
+## Part 2: Nest
+
+Pick 1-2 topic files from your knowledge base and review them:
+- Is the information still accurate and up to date?
+- Are there duplicates that should be consolidated?
+- Is anything important enough to promote to \`pkb/essentials.md\`?
+- Is anything in \`pkb/essentials.md\` that's no longer essential? Demote it to a topic file.
+- Are any threads in \`pkb/threads.md\` completed or stale? Remove them.
+- Is any file getting too long? Consider splitting it.
+- Should any topic file be restructured for clarity?
+
+Make improvements as you see fit. This is your knowledge base — keep it sharp.`;
+
+export interface FilingDeps {
+  processMessage: (
+    conversationId: string,
+    content: string,
+    options?: { speed?: Speed },
+  ) => Promise<{ messageId: string }>;
+  onConversationCreated?: (info: {
+    conversationId: string;
+    title: string;
+  }) => void;
+  getCurrentHour?: () => number;
+}
+
+export class FilingService {
+  private readonly deps: FilingDeps;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private activeRun: Promise<void> | null = null;
+  private _lastRunAt: number | null = null;
+  private _nextRunAt: number | null = null;
+
+  constructor(deps: FilingDeps) {
+    this.deps = deps;
+  }
+
+  get lastRunAt(): number | null {
+    return this._lastRunAt;
+  }
+
+  get nextRunAt(): number | null {
+    return this._nextRunAt;
+  }
+
+  start(): void {
+    const config = getConfig().filing;
+    if (!config.enabled) {
+      log.info("Filing service disabled by config");
+      this._nextRunAt = null;
+      return;
+    }
+    if (this.timer) return;
+
+    log.info({ intervalMs: config.intervalMs }, "Filing service started");
+    this.scheduleNextRun(config.intervalMs);
+    this.timer = setInterval(() => {
+      this.runOnce().catch((err) => {
+        log.error({ err }, "Filing runOnce failed");
+      });
+    }, config.intervalMs);
+  }
+
+  reconfigure(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this._nextRunAt = null;
+    this.start();
+  }
+
+  async stop(): Promise<void> {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this._nextRunAt = null;
+    if (this.activeRun) {
+      let timerId: ReturnType<typeof setTimeout>;
+      const timeout = new Promise<void>((resolve) => {
+        timerId = setTimeout(resolve, 5_000);
+      });
+      await Promise.race([this.activeRun, timeout]);
+      clearTimeout(timerId!);
+    }
+    log.info("Filing service stopped");
+  }
+
+  async runOnce({ force = false }: { force?: boolean } = {}): Promise<boolean> {
+    const config = getConfig().filing;
+    if (!force && !config.enabled) return false;
+
+    if (
+      !force &&
+      config.activeHoursStart != null &&
+      config.activeHoursEnd != null
+    ) {
+      const hour = this.deps.getCurrentHour?.() ?? new Date().getHours();
+      if (
+        !isWithinActiveHours(
+          hour,
+          config.activeHoursStart,
+          config.activeHoursEnd,
+        )
+      ) {
+        log.debug("Outside active hours, skipping filing");
+        this.scheduleNextRun(config.intervalMs);
+        return false;
+      }
+    }
+
+    if (this.activeRun) {
+      log.debug("Previous filing run still active, skipping");
+      return false;
+    }
+
+    // Skip if buffer is empty — no work to do
+    if (!force && !this.hasBufferContent()) {
+      log.debug("Buffer is empty, skipping filing");
+      this.scheduleNextRun(config.intervalMs);
+      return false;
+    }
+
+    const run = this.executeRun();
+    this.activeRun = run;
+    try {
+      await Promise.race([
+        run,
+        new Promise<never>((_, reject) =>
+          setTimeout(
+            () => reject(new Error("Filing execution timed out")),
+            FILING_TIMEOUT_MS,
+          ),
+        ),
+      ]);
+    } finally {
+      this.activeRun = null;
+      this._lastRunAt = Date.now();
+      this.scheduleNextRun(getConfig().filing.intervalMs);
+    }
+    return true;
+  }
+
+  private scheduleNextRun(intervalMs: number): void {
+    this._nextRunAt = Date.now() + intervalMs;
+  }
+
+  private hasBufferContent(): boolean {
+    const bufferPath = join(getWorkspaceDir(), "pkb", "buffer.md");
+    if (!existsSync(bufferPath)) return false;
+    try {
+      const content = stripCommentLines(
+        readFileSync(bufferPath, "utf-8"),
+      ).trim();
+      return content.length > 0;
+    } catch {
+      return false;
+    }
+  }
+
+  private async executeRun(): Promise<void> {
+    log.info("Running filing job");
+
+    try {
+      const config = getConfig().filing;
+
+      const conversation = bootstrapConversation({
+        conversationType: "background",
+        source: "filing",
+        groupId: "system:background",
+        origin: "filing",
+        systemHint: "Filing",
+      });
+
+      this.deps.onConversationCreated?.({
+        conversationId: conversation.id,
+        title: "Filing",
+      });
+
+      await this.deps.processMessage(conversation.id, FILING_PROMPT_TEMPLATE, {
+        speed: config.speed,
+      });
+
+      log.info({ conversationId: conversation.id }, "Filing job completed");
+    } catch (err) {
+      log.error({ err }, "Filing job failed");
+    }
+  }
+}
+
+function isWithinActiveHours(
+  hour: number,
+  start: number,
+  end: number,
+): boolean {
+  if (start <= end) {
+    return hour >= start && hour < end;
+  }
+  return hour >= start || hour < end;
+}

package/src/heartbeat/heartbeat-service.ts

@@ -1,18 +1,69 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
 import { getConfig } from "../config/loader.js";
 import type { Speed } from "../config/schemas/inference.js";
 import type { HeartbeatAlert } from "../daemon/message-protocol.js";
 import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
+import { isTemplateContent } from "../prompts/system-prompt.js";
 import { readTextFileSync } from "../util/fs.js";
 import { getLogger } from "../util/logger.js";
-import { getWorkspacePromptPath } from "../util/platform.js";
+import { getWorkspaceDir, getWorkspacePromptPath } from "../util/platform.js";
 import { stripCommentLines } from "../util/strip-comment-lines.js";
 
 const log = getLogger("heartbeat-check");
 
 const DEFAULT_CHECKLIST = `- Check in with yourself. Read NOW.md. Is it still accurate? Update it if anything has changed.
 - Think about your user. Is there anything from recent conversations you should follow up on? Anything you noticed that you should bring up?
+- Have a thought. Think about something your user would find interesting or worth talking about. A follow-up, a connection you made, something you came across. Give them a reason to open a conversation.
 - Check if there's anything on the horizon — events, deadlines, things they mentioned wanting to do.
-- If you have a thought worth sharing, send it. A follow-up, a useful find, a check-in. Not every beat, but when it feels right.`;
+- If you have a thought worth sharing, send it. A follow-up, a useful find, a check-in. Not every beat, but when it feels right.
+- If something has happened since your last journal entry, write one. Even a few sentences. The journal is how future-you stays connected.`;
+
+const REENGAGEMENT_COOLDOWN_MS = 18 * 60 * 60 * 1000; // 18 hours
+const HEARTBEAT_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+
+/** @internal Exported for testing. */
+export function isShallowProfile(): boolean {
+  try {
+    const identityPath = getWorkspacePromptPath("IDENTITY.md");
+    const userPath = getWorkspacePromptPath("USER.md");
+    const rawIdentity = readTextFileSync(identityPath);
+    const rawUser = readTextFileSync(userPath);
+    const identity = rawIdentity != null ? stripCommentLines(rawIdentity) : null;
+    const user = rawUser != null ? stripCommentLines(rawUser) : null;
+    return (
+      isTemplateContent(identity, "IDENTITY.md") &&
+      isTemplateContent(user, "USER.md")
+    );
+  } catch {
+    return false;
+  }
+}
+
+function getReengagementTimestampPath(): string {
+  return join(getWorkspaceDir(), ".reengagement-ts");
+}
+
+function isReengagementCooldownElapsed(): boolean {
+  const tsPath = getReengagementTimestampPath();
+  if (!existsSync(tsPath)) return true;
+  try {
+    const lastTs = parseInt(readFileSync(tsPath, "utf-8").trim(), 10);
+    if (isNaN(lastTs)) return true;
+    return Date.now() - lastTs >= REENGAGEMENT_COOLDOWN_MS;
+  } catch {
+    return true;
+  }
+}
+
+function recordReengagementTimestamp(): void {
+  try {
+    writeFileSync(getReengagementTimestampPath(), Date.now().toString());
+  } catch {
+    // Best-effort; don't block the heartbeat.
+  }
+}
 
 export interface HeartbeatDeps {
   processMessage: (
@@ -141,6 +192,7 @@ export class HeartbeatService {
           },
           "Outside active hours, skipping",
         );
+        this.scheduleNextRun(config.intervalMs);
         return false;
       }
     }
@@ -153,10 +205,34 @@ export class HeartbeatService {
 
     const run = this.executeRun();
     this.activeRun = run;
+    // Clear activeRun once executeRun finishes. On timeout, runOnce releases
+    // activeRun separately (see catch block below) so future runs aren't
+    // permanently blocked. The .finally() handler still serves as the
+    // normal-completion cleanup path and uses an identity guard to avoid
+    // clearing a different run's activeRun.
+    run.finally(() => {
+      if (this.activeRun === run) {
+        this.activeRun = null;
+      }
+    }).catch(() => {}); // Suppress unhandled rejection if executeRun rejects
+
+    let timerId: ReturnType<typeof setTimeout> | undefined;
     try {
-      await run;
-    } finally {
+      const timeout = new Promise<never>((_, reject) => {
+        timerId = setTimeout(
+          () => reject(new Error("Heartbeat execution timed out")),
+          HEARTBEAT_TIMEOUT_MS,
+        );
+      });
+      timeout.catch(() => {}); // Prevent unhandled rejection if run resolves first
+      await Promise.race([run, timeout]);
+    } catch (err) {
+      log.warn({ err }, "Heartbeat run timed out");
+      // Release activeRun so the overlap guard doesn't permanently block
+      // future heartbeat runs when executeRun hangs past the timeout.
       this.activeRun = null;
+    } finally {
+      clearTimeout(timerId);
       this._lastRunAt = Date.now();
       this.scheduleNextRun(getConfig().heartbeat.intervalMs);
     }
@@ -173,11 +249,12 @@ export class HeartbeatService {
     try {
       const config = getConfig().heartbeat;
       const checklist = this.readChecklist();
-      const prompt = this.buildPrompt(checklist);
+      const { prompt, includedReengagement } = this.buildPrompt(checklist);
 
       const conversation = bootstrapConversation({
         conversationType: "background",
         source: "heartbeat",
+        groupId: "system:background",
         origin: "heartbeat",
         systemHint: "Heartbeat",
       });
@@ -190,6 +267,11 @@ export class HeartbeatService {
       await this.deps.processMessage(conversation.id, prompt, {
         speed: config.speed,
       });
+
+      if (includedReengagement) {
+        recordReengagementTimestamp();
+      }
+
       log.info({ conversationId: conversation.id }, "Heartbeat completed");
     } catch (err) {
       log.error({ err }, "Heartbeat failed");
@@ -213,8 +295,8 @@ export class HeartbeatService {
   }
 
   /** @internal Exposed for testing. */
-  buildPrompt(checklist: string): string {
-    return `You are running a periodic heartbeat check. Review the following checklist and take any necessary actions.
+  buildPrompt(checklist: string): { prompt: string; includedReengagement: boolean } {
+    let prompt = `You are running a periodic heartbeat check. Review the following checklist and take any necessary actions.
 
 <heartbeat-checklist>
 ${checklist}
@@ -225,6 +307,14 @@ After completing your review, end your response with one of:
 - HEARTBEAT_OK — if everything looks good, no action needed
 - HEARTBEAT_ALERT — if you found issues that need attention (describe them before this marker)
 </heartbeat-disposition>`;
+
+    let includedReengagement = false;
+    if (isShallowProfile() && isReengagementCooldownElapsed()) {
+      includedReengagement = true;
+      prompt += `\n\n<relationship-depth>\nYou don't know much about this person yet — their profile is still sparse. If the moment feels right during this beat, gently invite them to share something about themselves. Not an interrogation — something natural like "I realized I don't actually know much about what you do. Fill me in sometime?" Only do this occasionally, not every beat. If they engage, save what you learn.\n</relationship-depth>`;
+    }
+
+    return { prompt, includedReengagement };
   }
 }
 

package/src/hooks/cli.ts

@@ -20,7 +20,7 @@ export function registerHooksCommand(program: Command): void {
 Hooks are user-installed scripts that run in response to assistant lifecycle
 events (e.g. tool invocations, message sends). Each hook is a directory
 containing a hook.json manifest and a script file. Hooks are stored in
-~/.vellum/hooks/ and must be explicitly enabled after installation.
+$VELLUM_WORKSPACE_DIR/hooks/ and must be explicitly enabled after installation.
 
 Examples:
   $ assistant hooks list
@@ -136,7 +136,7 @@ Arguments:
          The manifest must have name, script, description, version, and at
          least one valid event.
 
-Copies the hook directory into ~/.vellum/hooks/<name>/ and registers it as
+Copies the hook directory into $VELLUM_WORKSPACE_DIR/hooks/<name>/ and registers it as
 disabled by default. Run 'assistant hooks enable <name>' to activate.
 
 Examples:

package/src/hooks/runner.ts

@@ -1,42 +1,19 @@
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
-import { basename, extname, join } from "node:path";
+import { extname, join } from "node:path";
 
-import { pathExists } from "../util/fs.js";
+import { ensureBun } from "../util/bun-runtime.js";
 import { getWorkspaceDir } from "../util/platform.js";
 import { getHookSettings } from "./config.js";
 import type { DiscoveredHook, HookEventData } from "./types.js";
 
-/**
- * Resolve a usable bun runtime path. When the daemon runs under plain bun
- * (dev mode), `process.execPath` is the bun CLI and works directly.  When the
- * daemon is a `bun build --compile` binary, `process.execPath` points to the
- * compiled binary itself -- spawning it with `['run', script]` would re-launch
- * the daemon.  In that case we locate bun via PATH or at `~/.bun/bin/bun`.
- */
-function resolveBunPath(): string {
-  const execBasename = basename(process.execPath);
-  if (execBasename === "bun" || execBasename === "bun.exe") {
-    return process.execPath;
-  }
-
-  // Compiled-binary mode -- find a standalone bun runtime.
-  const found = Bun.which("bun");
-  if (found) return found;
-
-  const fallback = join(homedir(), ".bun", "bin", "bun");
-  if (pathExists(fallback)) return fallback;
-
-  throw new Error(
-    "Cannot find a bun runtime to execute .ts hooks. " +
-      "Install bun (https://bun.sh) or ensure it is on your PATH.",
-  );
-}
-
-function getSpawnArgs(scriptPath: string): { command: string; args: string[] } {
+async function getSpawnArgs(
+  scriptPath: string,
+): Promise<{ command: string; args: string[] }> {
   const ext = extname(scriptPath);
   if (ext === ".ts") {
-    return { command: resolveBunPath(), args: ["run", scriptPath] };
+    const bunPath = await ensureBun();
+    return { command: bunPath, args: ["run", scriptPath] };
   }
   return { command: scriptPath, args: [] };
 }
@@ -54,15 +31,15 @@ export async function runHookScript(
 ): Promise<HookRunResult> {
   const timeoutMs = options?.timeoutMs ?? 5000;
 
+  let spawnResult: { command: string; args: string[] };
+  try {
+    spawnResult = await getSpawnArgs(hook.scriptPath);
+  } catch (err) {
+    return { exitCode: null, stdout: "", stderr: (err as Error).message };
+  }
+  const { command, args } = spawnResult;
+
   return new Promise<HookRunResult>((resolve) => {
-    let spawnResult: { command: string; args: string[] };
-    try {
-      spawnResult = getSpawnArgs(hook.scriptPath);
-    } catch (err) {
-      resolve({ exitCode: null, stdout: "", stderr: (err as Error).message });
-      return;
-    }
-    const { command, args } = spawnResult;
     const child = spawn(command, args, {
       cwd: hook.dir,
       env: {

package/src/inbound/platform-callback-registration.ts

@@ -1,7 +1,7 @@
 /**
- * Platform callback route registration for containerized deployments.
+ * Platform callback route registration for platform-managed deployments.
  *
- * When the assistant daemon runs inside a container (IS_CONTAINERIZED=true)
+ * When the assistant daemon runs as a platform-managed instance (IS_PLATFORM=true)
  * with a configured VELLUM_PLATFORM_URL and PLATFORM_ASSISTANT_ID, external
  * service callbacks (Twilio webhooks, OAuth redirects, Telegram webhooks, etc.)
  * must route through the platform's gateway proxy instead of hitting the
@@ -9,7 +9,7 @@
  *
  * This module registers callback routes with the platform's internal
  * gateway endpoint so the platform knows how to forward inbound provider
- * webhooks to the correct containerized assistant instance.
+ * webhooks to the correct platform-managed assistant instance.
  *
  * The platform endpoint is:
  *   POST {VELLUM_PLATFORM_URL}/v1/internal/gateway/callback-routes/register/
@@ -23,7 +23,7 @@ import {
   getPlatformBaseUrl,
   getPlatformInternalApiKey,
 } from "../config/env.js";
-import { getIsContainerized } from "../config/env-registry.js";
+import { getIsPlatform } from "../config/env-registry.js";
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";
@@ -31,7 +31,7 @@ import { getLogger } from "../util/logger.js";
 const log = getLogger("platform-callback-registration");
 
 export interface PlatformCallbackRegistrationContext {
-  containerized: boolean;
+  isPlatform: boolean;
   platformBaseUrl: string;
   assistantId: string;
   hasInternalApiKey: boolean;
@@ -42,21 +42,21 @@ export interface PlatformCallbackRegistrationContext {
 
 /**
  * Whether the daemon should register callback routes with the platform.
- * True when IS_CONTAINERIZED, VELLUM_PLATFORM_URL, and PLATFORM_ASSISTANT_ID
+ * True when IS_PLATFORM, VELLUM_PLATFORM_URL, and PLATFORM_ASSISTANT_ID
  * are all set. Intentionally does **not** require the managed proxy API key
  * so that callback-only flows (OAuth transport, Telegram/Twilio callback
  * registration) work during partial bootstrap before the key is injected.
  */
 export function shouldUsePlatformCallbacks(): boolean {
   return (
-    getIsContainerized() &&
+    getIsPlatform() &&
     !!getPlatformBaseUrl() &&
     !!getPlatformAssistantId()
   );
 }
 
 export async function resolvePlatformCallbackRegistrationContext(): Promise<PlatformCallbackRegistrationContext> {
-  const containerized = getIsContainerized();
+  const platform = getIsPlatform();
   const [storedBaseUrlRaw, storedAssistantIdRaw, storedAssistantApiKeyRaw] =
     await Promise.all([
       getSecureKeyAsync(credentialKey("vellum", "platform_base_url")),
@@ -80,14 +80,14 @@ export async function resolvePlatformCallbackRegistrationContext(): Promise<Plat
       : null;
 
   return {
-    containerized,
+    isPlatform: platform,
     platformBaseUrl,
     assistantId,
     hasInternalApiKey: internalApiKey.length > 0,
     hasAssistantApiKey: assistantApiKey.length > 0,
     authHeader,
     enabled:
-      containerized &&
+      platform &&
       platformBaseUrl.length > 0 &&
       assistantId.length > 0 &&
       authHeader !== null,
@@ -119,7 +119,7 @@ export async function registerCallbackRoute(
   const context = await resolvePlatformCallbackRegistrationContext();
   if (!context.enabled || !context.authHeader) {
     throw new Error(
-      "Platform callbacks not available — missing containerized platform registration context",
+      "Platform callbacks not available — missing platform registration context",
     );
   }
 
@@ -166,7 +166,7 @@ export async function registerCallbackRoute(
 }
 
 /**
- * Resolve a callback URL, registering with the platform when containerized.
+ * Resolve a callback URL, registering with the platform when platform-managed.
  *
  * When platform callbacks are enabled, registers the route and returns the
  * platform's stable callback URL (optionally with query parameters appended).
@@ -176,7 +176,7 @@ export async function registerCallbackRoute(
  * string) rather than an eagerly-evaluated string. This is critical because
  * the direct URL builders (e.g. `getTwilioVoiceWebhookUrl`) call
  * `getPublicBaseUrl()` which throws when no public ingress URL is configured.
- * In containerized environments that rely solely on platform callbacks, the
+ * In platform-managed environments that rely solely on platform callbacks, the
  * direct URL is never needed — deferring evaluation avoids the throw.
  *
  * @param directUrl - Lazy supplier for the direct callback URL.
@@ -204,7 +204,7 @@ export async function resolveCallbackUrl(
     }
     return url;
   } catch (err) {
-    // In managed/containerized mode there is no local-ingress fallback and
+    // In platform-managed mode there is no local-ingress fallback and
     // ngrok is not applicable. Surface a clear error so callers (and the
     // user) understand this is a platform-side issue, not a tunnel problem.
     const detail = err instanceof Error ? err.message : String(err);

package/src/mcp/client.ts

@@ -5,6 +5,7 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 
 import type { McpTransport } from "../config/schemas/mcp.js";
+import { shouldUsePlatformCallbacks } from "../inbound/platform-callback-registration.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";
 import { McpOAuthProvider } from "./mcp-oauth-provider.js";
@@ -63,9 +64,14 @@ export class McpClient {
         `mcp:${this.serverId}:tokens`,
       );
       if (cachedTokens) {
+        const callbackTransport = shouldUsePlatformCallbacks()
+          ? "gateway"
+          : "loopback";
         this.oauthProvider = new McpOAuthProvider(
           this.serverId,
           transportConfig.url,
+          /* interactive */ false,
+          callbackTransport,
         );
       }
     }