@vellumai/assistant 0.6.0 → 0.6.1

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,7 +249,7 @@ 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",
@@ -191,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");
@@ -214,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}
@@ -226,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/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,
         );
       }
     }

package/src/mcp/mcp-oauth-provider.ts

@@ -2,9 +2,21 @@
  * OAuthClientProvider implementation for MCP servers.
  *
  * Uses secure-keys (credential store) for persistent credential storage
- * and a loopback HTTP server for the browser callback.
+ * and either a loopback HTTP server or the gateway callback registry
+ * for the browser callback.
+ *
+ * Two callback transports:
+ *
+ * 1. **Loopback** (default) — starts a temporary HTTP server on localhost.
+ *    Works when the daemon runs on the user's machine (desktop app).
+ *
+ * 2. **Gateway** — routes callbacks through the platform's public ingress
+ *    URL and the in-memory oauth-callback-registry. Used when the daemon
+ *    runs inside Docker/platform where localhost is unreachable from the
+ *    user's browser.
  */
 
+import { randomBytes } from "node:crypto";
 import { createServer, type Server } from "node:http";
 
 import type {
@@ -22,8 +34,8 @@ import {
   getSecureKeyAsync,
   setSecureKeyAsync,
 } from "../security/secure-keys.js";
+import { openInHostBrowser } from "../util/browser.js";
 import { getLogger } from "../util/logger.js";
-import { isLinux, isMacOS } from "../util/platform.js";
 
 const log = getLogger("mcp-oauth");
 
@@ -46,24 +58,41 @@ export interface McpOAuthCallbackResult {
   codePromise: Promise<string>;
 }
 
+/** Which callback transport to use for receiving the OAuth redirect. */
+export type McpOAuthCallbackTransport = "loopback" | "gateway";
+
 export class McpOAuthProvider implements OAuthClientProvider {
   private readonly serverId: string;
   private readonly serverUrl: string;
   private readonly interactive: boolean;
+  private readonly callbackTransport: McpOAuthCallbackTransport;
   private _codeVerifier: string | undefined;
+  private _state: string | undefined;
   private _redirectUrl: string | undefined;
   private _codePromise: Promise<string> | null = null;
   private callbackServer: Server | null = null;
   private callbackTimeout: ReturnType<typeof setTimeout> | null = null;
+  /** Deferred resolver/rejector for the gateway code promise. */
+  private _gatewayCodeResolve: ((code: string) => void) | undefined;
+  private _gatewayCodeReject: ((err: Error) => void) | undefined;
 
   /**
    * @param interactive When true (e.g. `mcp auth` CLI), opens browser for OAuth.
    *                    When false (daemon), logs a message instead.
+   * @param callbackTransport Which transport to use for the OAuth redirect.
+   *   - `"loopback"` (default): localhost HTTP server — for desktop clients.
+   *   - `"gateway"`: platform ingress + callback registry — for Docker/platform.
    */
-  constructor(serverId: string, serverUrl: string, interactive = false) {
+  constructor(
+    serverId: string,
+    serverUrl: string,
+    interactive = false,
+    callbackTransport: McpOAuthCallbackTransport = "loopback",
+  ) {
     this.serverId = serverId;
     this.serverUrl = serverUrl;
     this.interactive = interactive;
+    this.callbackTransport = callbackTransport;
   }
 
   // --- redirectUrl ---
@@ -161,6 +190,26 @@ export class McpOAuthProvider implements OAuthClientProvider {
     return this._codeVerifier;
   }
 
+  // --- State (CSRF token for OAuth) ---
+
+  /**
+   * Return a `state` value for the authorization URL.
+   *
+   * The MCP SDK calls `provider.state?.()` and, when the return value is
+   * truthy, appends it as the `state` query parameter.  For the **gateway**
+   * transport the state is mandatory because it is the key used by the
+   * `oauth-callback-registry` to route the redirect back to this flow.
+   * For the **loopback** transport the state is optional (the loopback
+   * server matches on the callback URL itself), but we generate one anyway
+   * for defense-in-depth.
+   */
+  async state(): Promise<string> {
+    if (!this._state) {
+      this._state = randomBytes(16).toString("hex");
+    }
+    return this._state;
+  }
+
   // --- Discovery State ---
 
   async discoveryState(): Promise<OAuthDiscoveryState | undefined> {
@@ -191,6 +240,35 @@ export class McpOAuthProvider implements OAuthClientProvider {
   async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
     const url = authorizationUrl.toString();
 
+    // For gateway transport, extract the SDK-generated `state` from the
+    // authorization URL and register it with the callback registry now.
+    if (
+      this.callbackTransport === "gateway" &&
+      this._gatewayCodeResolve &&
+      this._gatewayCodeReject
+    ) {
+      const sdkState = authorizationUrl.searchParams.get("state");
+      if (sdkState) {
+        // Dynamic import to avoid circular deps
+        const { registerPendingCallback } =
+          await import("../security/oauth-callback-registry.js");
+        registerPendingCallback(
+          sdkState,
+          this._gatewayCodeResolve,
+          this._gatewayCodeReject,
+        );
+        log.info(
+          { serverId: this.serverId, state: sdkState },
+          "MCP OAuth gateway callback registered with SDK state",
+        );
+      } else {
+        log.warn(
+          { serverId: this.serverId },
+          "Authorization URL missing state parameter — gateway callback may not resolve",
+        );
+      }
+    }
+
     if (!this.interactive) {
       // Daemon mode — don't open browser, just log guidance
       log.info(
@@ -208,28 +286,8 @@ export class McpOAuthProvider implements OAuthClientProvider {
       `[MCP] Opening browser for OAuth authorization of "${this.serverId}"...`,
     );
 
-    try {
-      const { execFile } = await import("node:child_process");
-      const onError = (err: Error | null) => {
-        if (err) {
-          log.warn({ err }, "Failed to open browser");
-          console.log(`[MCP] Please open this URL in your browser:\n${url}`);
-        }
-      };
-      if (isMacOS()) {
-        execFile("open", [url], onError);
-      } else if (isLinux()) {
-        execFile("xdg-open", [url], onError);
-      } else {
-        log.warn(
-          "Unsupported platform for browser open — please visit the URL manually",
-        );
-        console.log(`[MCP] Please open this URL in your browser:\n${url}`);
-      }
-    } catch (err) {
-      log.warn({ err }, "Failed to open browser");
-      console.log(`[MCP] Please open this URL in your browser:\n${url}`);
-    }
+    await openInHostBrowser(url);
+    console.log(`[MCP] If the browser did not open, visit this URL:\n${url}`);
   }
 
   // --- Invalidate Credentials ---
@@ -272,6 +330,7 @@ export class McpOAuthProvider implements OAuthClientProvider {
     }
     if (scope === "all" || scope === "verifier") {
       this._codeVerifier = undefined;
+      this._state = undefined;
     }
     if (scope === "all" || scope === "discovery") {
       const result = await deleteSecureKeyAsync(discoveryKey(this.serverId));
@@ -292,10 +351,64 @@ export class McpOAuthProvider implements OAuthClientProvider {
   // --- Callback Server ---
 
   /**
-   * Start a loopback HTTP server to receive the OAuth callback.
-   * Returns a promise that resolves with the authorization code.
+   * Start listening for the OAuth callback.
+   *
+   * - **Loopback transport**: starts a temporary HTTP server on localhost.
+   * - **Gateway transport**: registers a pending callback with the
+   *   oauth-callback-registry and resolves a public redirect URL via
+   *   the platform callback registration system.
+   *
+   * Returns a promise that resolves with the authorization code promise.
    */
   startCallbackServer(): Promise<McpOAuthCallbackResult> {
+    if (this.callbackTransport === "gateway") {
+      return this.startGatewayCallback();
+    }
+    return this.startLoopbackServer();
+  }
+
+  /**
+   * Gateway transport: resolve the public redirect URL and create a
+   * deferred code promise.  The actual `registerPendingCallback` call
+   * is deferred until `redirectToAuthorization` where we can extract
+   * the SDK-generated `state` parameter from the authorization URL.
+   */
+  private async startGatewayCallback(): Promise<McpOAuthCallbackResult> {
+    const { resolveCallbackUrl } =
+      await import("../inbound/platform-callback-registration.js");
+    const { getOAuthCallbackUrl } =
+      await import("../inbound/public-ingress-urls.js");
+    const { loadConfig } = await import("../config/loader.js");
+
+    const appConfig = loadConfig();
+    const redirectUrl = await resolveCallbackUrl(
+      () => getOAuthCallbackUrl(appConfig),
+      "webhooks/oauth/callback",
+      "mcp_oauth",
+    );
+
+    this._redirectUrl = redirectUrl;
+
+    // Create a deferred promise — it will be wired to the callback
+    // registry in redirectToAuthorization() once we know the SDK's state.
+    const codePromise = new Promise<string>((resolve, reject) => {
+      this._gatewayCodeResolve = resolve;
+      this._gatewayCodeReject = reject;
+    });
+    this._codePromise = codePromise;
+
+    log.info(
+      { serverId: this.serverId, redirectUrl },
+      "MCP OAuth gateway callback prepared (awaiting state from auth URL)",
+    );
+
+    return { codePromise };
+  }
+
+  /**
+   * Loopback transport: start a temporary HTTP server on localhost.
+   */
+  private startLoopbackServer(): Promise<McpOAuthCallbackResult> {
     return new Promise((resolveSetup, rejectSetup) => {
       let settled = false;
       let listening = false;
@@ -423,6 +536,15 @@ export class McpOAuthProvider implements OAuthClientProvider {
       this.callbackServer.close();
       this.callbackServer = null;
     }
+    // Gateway transport cleanup — reject the deferred promise so callers
+    // awaiting codePromise don't hang indefinitely.
+    if (this._gatewayCodeReject) {
+      this._gatewayCodeReject(
+        new Error("MCP OAuth gateway callback cancelled"),
+      );
+      this._gatewayCodeResolve = undefined;
+      this._gatewayCodeReject = undefined;
+    }
   }
 }
 

package/src/memory/admin.ts

@@ -7,14 +7,20 @@ import { getConversationMemoryScopeId } from "./conversation-crud.js";
 import { getDb, rawGet } from "./db.js";
 import { getMemoryBackendStatus } from "./embedding-backend.js";
 import { handleRecall, type RecallResult } from "./graph/tool-handlers.js";
-import { enqueueBackfillJob, enqueueRebuildIndexJob, MIN_SEGMENT_CHARS } from "./indexer.js";
 import {
-  enqueueMemoryJob,
-  getMemoryJobCounts,
-} from "./jobs-store.js";
+  enqueueBackfillJob,
+  enqueueRebuildIndexJob,
+  MIN_SEGMENT_CHARS,
+} from "./indexer.js";
+import { enqueueMemoryJob, getMemoryJobCounts } from "./jobs-store.js";
 import { withQdrantBreaker } from "./qdrant-circuit-breaker.js";
 import { getQdrantClient } from "./qdrant-client.js";
-import { conversations, memorySegments, memorySummaries, messages } from "./schema.js";
+import {
+  conversations,
+  memorySegments,
+  memorySummaries,
+  messages,
+} from "./schema.js";
 
 const log = getLogger("memory-admin");
 
@@ -69,10 +75,6 @@ export function requestMemoryRebuildIndex(): string {
   return id;
 }
 
-export function requestMemoryCleanup(_retentionMs?: number): void {
-  log.info("Memory cleanup requested (legacy items table dropped — no-op)");
-}
-
 export async function queryMemory(
   query: string,
   _conversationId: string,
@@ -94,9 +96,9 @@ export interface CleanupShortSegmentsResult {
  * These short fragments waste embedding budget, retrieval slots, and
  * injection tokens.
  */
-export async function cleanupShortSegments(
-  opts?: { dryRun?: boolean },
-): Promise<CleanupShortSegmentsResult> {
+export async function cleanupShortSegments(opts?: {
+  dryRun?: boolean;
+}): Promise<CleanupShortSegmentsResult> {
   const db = getDb();
 
   const shortSegments = db
@@ -117,18 +119,22 @@ export async function cleanupShortSegments(
       await withQdrantBreaker(() => qdrant.deleteByTarget("segment", row.id));
     } catch (err) {
       // Keep the SQLite row so the target ID is preserved for retry
-      log.warn({ segmentId: row.id, err }, "Qdrant deletion failed — skipping SQLite deletion to preserve target ID");
+      log.warn(
+        { segmentId: row.id, err },
+        "Qdrant deletion failed — skipping SQLite deletion to preserve target ID",
+      );
       failed++;
       continue;
     }
 
-    db.delete(memorySegments)
-      .where(eq(memorySegments.id, row.id))
-      .run();
+    db.delete(memorySegments).where(eq(memorySegments.id, row.id)).run();
     removed++;
   }
 
-  log.info({ removed, failed, threshold: MIN_SEGMENT_CHARS }, "Cleaned up short segments");
+  log.info(
+    { removed, failed, threshold: MIN_SEGMENT_CHARS },
+    "Cleaned up short segments",
+  );
   return { removed, failed };
 }
 
@@ -160,7 +166,7 @@ export function findReextractTargets(limit: number): ReextractTarget[] {
     .from(conversations)
     .leftJoin(messages, eq(messages.conversationId, conversations.id))
     .where(
-      sql`${conversations.conversationType} NOT IN ('background', 'private')`,
+      sql`${conversations.conversationType} NOT IN ('background', 'private', 'scheduled')`,
     )
     .groupBy(conversations.id)
     .orderBy(desc(sql`count(${messages.id})`))
@@ -204,25 +210,21 @@ export function findReextractTarget(
 /**
  * Queue re-extraction for a set of conversations.
  * Resets extraction checkpoints and clears extraction summaries so the
- * batch extraction handler processes all messages from scratch with
+ * graph extraction handler processes all messages from scratch with
  * expanded supersession context.
  */
-export function requestReextract(
-  targets: ReextractTarget[],
-): { jobIds: string[] } {
+export function requestReextract(targets: ReextractTarget[]): {
+  jobIds: string[];
+} {
   const db = getDb();
   const jobIds: string[] = [];
 
   for (const target of targets) {
     const { conversationId } = target;
 
-    // Reset batch extraction checkpoints
-    deleteMemoryCheckpoint(
-      `batch_extract:${conversationId}:last_message_id`,
-    );
-    deleteMemoryCheckpoint(
-      `batch_extract:${conversationId}:pending_count`,
-    );
+    // Reset graph extraction checkpoints
+    deleteMemoryCheckpoint(`graph_extract:${conversationId}:last_ts`);
+    deleteMemoryCheckpoint(`graph_extract:${conversationId}:pending_count`);
 
     // Clear the extraction summary so it starts fresh
     db.delete(memorySummaries)
@@ -234,12 +236,11 @@ export function requestReextract(
       )
       .run();
 
-    // Resolve scope and enqueue with fullReextract flag
+    // Resolve scope and enqueue re-extraction
     const scopeId = getConversationMemoryScopeId(conversationId);
-    const jobId = enqueueMemoryJob("batch_extract", {
+    const jobId = enqueueMemoryJob("graph_extract", {
       conversationId,
       scopeId,
-      fullReextract: true,
     });
     jobIds.push(jobId);
 

package/src/memory/app-store.ts

@@ -216,6 +216,8 @@ export function generateAppDirName(
 
 /** Cache of id -> dirName mappings to avoid repeated filesystem scans. */
 const idToDirNameCache = new Map<string, string>();
+/** Reverse cache: dirName -> id. */
+const dirNameToIdCache = new Map<string, string>();
 
 /**
  * Resolve an app's directory name and path from its ID.
@@ -265,12 +267,79 @@ export function getAppDirPath(appId: string): string {
   return resolveAppDir(appId).appDir;
 }
 
+/**
+ * Resolve an app ID from its directory name (slug).
+ * Checks caches first, then reads the JSON definition file directly.
+ */
+export function resolveAppIdByDirName(dirName: string): string | null {
+  const cached = dirNameToIdCache.get(dirName);
+  if (cached) return cached;
+
+  // Check forward cache (reverse iteration)
+  for (const [id, dn] of idToDirNameCache) {
+    if (dn === dirName) {
+      dirNameToIdCache.set(dirName, id);
+      return id;
+    }
+  }
+
+  // Read the JSON definition file directly
+  const dir = getAppsDir();
+  const jsonPath = join(dir, `${dirName}.json`);
+  if (existsSync(jsonPath)) {
+    try {
+      const raw = readFileSync(jsonPath, "utf-8");
+      const parsed = JSON.parse(raw) as { id?: string; dirName?: string };
+      if (parsed.id) {
+        dirNameToIdCache.set(dirName, parsed.id);
+        idToDirNameCache.set(parsed.id, dirName);
+        return parsed.id;
+      }
+    } catch {
+      // skip malformed files
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extract app ID from an absolute file path if it falls within the apps
+ * directory and targets a source file (not records/ or dist/).
+ */
+export function resolveAppIdFromPath(filePath: string): string | null {
+  let appsDir: string;
+  try {
+    appsDir = getAppsDir();
+  } catch {
+    return null;
+  }
+  if (!filePath.startsWith(appsDir + "/")) return null;
+
+  const relPath = filePath.slice(appsDir.length + 1);
+  const slashIdx = relPath.indexOf("/");
+  if (slashIdx === -1) return null; // file directly in apps/ (e.g. the .json definition)
+
+  const dirName = relPath.slice(0, slashIdx);
+  const innerPath = relPath.slice(slashIdx + 1);
+
+  // Skip non-source directories
+  if (innerPath.startsWith("records/") || innerPath.startsWith("dist/")) {
+    return null;
+  }
+
+  return resolveAppIdByDirName(dirName);
+}
+
 /** Invalidate the id->dirName cache for a specific app or all apps. */
 function invalidateDirNameCache(appId?: string): void {
   if (appId) {
+    const dirName = idToDirNameCache.get(appId);
     idToDirNameCache.delete(appId);
+    if (dirName) dirNameToIdCache.delete(dirName);
   } else {
     idToDirNameCache.clear();
+    dirNameToIdCache.clear();
   }
 }
 

package/src/memory/conversation-bootstrap.ts

@@ -6,7 +6,7 @@ import {
 } from "./conversation-title-service.js";
 
 export interface BootstrapConversationOptions {
-  conversationType?: "standard" | "private" | "background";
+  conversationType?: "standard" | "private" | "background" | "scheduled";
   source?: string;
   origin: TitleOrigin;
   systemHint: string;