@vellumai/assistant 0.6.0 → 0.6.1

package/src/runtime/routes/subagents-routes.ts

@@ -34,15 +34,17 @@ export interface SubagentDetailResult {
   }>;
 }
 
-export function getSubagentDetail(
+/**
+ * Parse raw message rows into subagent detail events. Extracted as a pure
+ * function so it can be unit-tested without a database.
+ */
+export function parseSubagentMessages(
   subagentId: string,
-  conversationId: string,
+  messages: Array<{ role: string; content: string }>,
 ): SubagentDetailResult {
-  const subagentMsgs = getMessages(conversationId);
-
   // Extract objective from the first user message
   let objective: string | undefined;
-  const firstUser = subagentMsgs.find((m) => m.role === "user");
+  const firstUser = messages.find((m) => m.role === "user");
   if (firstUser) {
     try {
       const parsed = JSON.parse(firstUser.content);
@@ -67,7 +69,7 @@ export function getSubagentDetail(
     isError?: boolean;
   }> = [];
   const pendingTools = new Map<string, string>();
-  for (const m of subagentMsgs) {
+  for (const m of messages) {
     if (m.role !== "assistant" && m.role !== "user") continue;
     let content: unknown[];
     try {
@@ -101,7 +103,19 @@ export function getSubagentDetail(
         const toolUseId =
           typeof block.tool_use_id === "string" ? block.tool_use_id : "";
         const resultContent =
-          typeof block.content === "string" ? block.content : "";
+          typeof block.content === "string"
+            ? block.content
+            : Array.isArray(block.content)
+              ? (block.content as unknown[])
+                  .filter(
+                    (b): b is Record<string, unknown> =>
+                      isRecord(b) &&
+                      (b as Record<string, unknown>).type === "text" &&
+                      typeof (b as Record<string, unknown>).text === "string",
+                  )
+                  .map((b) => b.text as string)
+                  .join("\n")
+              : "";
         const isError = block.is_error === true;
         const toolName = toolUseId ? pendingTools.get(toolUseId) : undefined;
         events.push({
@@ -117,6 +131,13 @@ export function getSubagentDetail(
   return { subagentId, objective, events };
 }
 
+export function getSubagentDetail(
+  subagentId: string,
+  conversationId: string,
+): SubagentDetailResult {
+  return parseSubagentMessages(subagentId, getMessages(conversationId));
+}
+
 // ---------------------------------------------------------------------------
 // Route definitions
 // ---------------------------------------------------------------------------

package/src/runtime/routes/user-route-dispatcher.ts

@@ -0,0 +1,223 @@
+/**
+ * File-based route dispatcher for user-defined HTTP endpoints.
+ *
+ * Maps requests under the `/x/*` path prefix to handler modules in the
+ * workspace routes directory (`$VELLUM_WORKSPACE_DIR/routes/`). Each handler file
+ * exports named functions for HTTP methods (GET, POST, PUT, etc.) using
+ * the standard Web API Request/Response signature.
+ *
+ * Modules are lazily loaded on first request and cached by file path +
+ * mtime. When a file changes on disk, the next request reloads it via
+ * Bun's dynamic `import()` with a cache-busting query parameter.
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { getLogger } from "../../util/logger.js";
+import { getWorkspaceRoutesDir } from "../../util/platform.js";
+import { httpError } from "../http-errors.js";
+
+const log = getLogger("user-routes");
+
+/** HTTP methods that can be exported from a handler module. */
+const HTTP_METHODS = [
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "HEAD",
+  "OPTIONS",
+] as const;
+
+type HttpMethod = (typeof HTTP_METHODS)[number];
+
+/** The function signature that user-defined route handlers must follow. */
+type RouteHandler = (request: Request) => Response | Promise<Response>;
+
+/** A loaded handler module with its cached metadata. */
+interface CachedModule {
+  /** The module's exports (keyed by HTTP method name). */
+  handlers: Partial<Record<HttpMethod, RouteHandler>>;
+  /** Optional description exported by the module for display in CLI. */
+  description?: string;
+  /** The file's mtime at the time of loading, in milliseconds. */
+  mtimeMs: number;
+}
+
+/** Default per-request timeout for user-defined route handlers (30 seconds). */
+const DEFAULT_HANDLER_TIMEOUT_MS = 30_000;
+
+/** Supported file extensions for handler modules. */
+const HANDLER_EXTENSIONS = [".ts", ".js"] as const;
+
+export class UserRouteDispatcher {
+  private moduleCache = new Map<string, CachedModule>();
+  private handlerTimeoutMs: number;
+
+  constructor(options?: { handlerTimeoutMs?: number }) {
+    this.handlerTimeoutMs =
+      options?.handlerTimeoutMs ?? DEFAULT_HANDLER_TIMEOUT_MS;
+  }
+
+  /**
+   * Dispatch a request to the appropriate user-defined handler file.
+   *
+   * @param routePath The path after the `x/` prefix (e.g. `my-app/status`).
+   * @param request   The original HTTP request.
+   * @returns A Response from the handler, or an error response (404, 405, 500).
+   */
+  async dispatch(routePath: string, request: Request): Promise<Response> {
+    if (routePath.includes("..")) {
+      return httpError("BAD_REQUEST", "Path traversal is not allowed", 400);
+    }
+
+    const routesDir = getWorkspaceRoutesDir();
+    const filePath = this.resolveHandlerFile(routesDir, routePath);
+
+    if (!filePath) {
+      return httpError(
+        "NOT_FOUND",
+        `No route handler found for /x/${routePath}`,
+        404,
+      );
+    }
+
+    const mod = await this.loadModule(filePath);
+    const method = request.method as HttpMethod;
+    const handler = mod.handlers[method];
+
+    if (!handler) {
+      const allowed = HTTP_METHODS.filter((m) => m in mod.handlers);
+      return new Response(null, {
+        status: 405,
+        headers: { Allow: allowed.join(", ") },
+      });
+    }
+
+    return this.executeHandler(handler, request, routePath);
+  }
+
+  /**
+   * Resolve a route path to a handler file on disk.
+   *
+   * Checks for direct file matches first (`<path>.ts`, `<path>.js`),
+   * then falls back to index files (`<path>/index.ts`, `<path>/index.js`).
+   *
+   * Returns the absolute path to the handler file, or null if not found.
+   */
+  private resolveHandlerFile(
+    routesDir: string,
+    routePath: string,
+  ): string | null {
+    const basePath = join(routesDir, routePath);
+    const resolved = resolve(basePath);
+
+    // Ensure the resolved path is within the routes directory to prevent
+    // any path traversal that slipped through the initial check.
+    if (!resolved.startsWith(resolve(routesDir))) {
+      return null;
+    }
+
+    // Direct file match: routes/<path>.ts or routes/<path>.js
+    for (const ext of HANDLER_EXTENSIONS) {
+      const candidate = `${resolved}${ext}`;
+      if (existsSync(candidate)) {
+        return candidate;
+      }
+    }
+
+    // Index file convention: routes/<path>/index.ts or routes/<path>/index.js
+    for (const ext of HANDLER_EXTENSIONS) {
+      const candidate = join(resolved, `index${ext}`);
+      if (existsSync(candidate)) {
+        return candidate;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Load a handler module, using the mtime-based cache when possible.
+   *
+   * On cache miss or stale mtime, the module is re-imported via Bun's
+   * dynamic `import()` with a cache-busting query parameter derived
+   * from the file's current mtime.
+   */
+  private async loadModule(filePath: string): Promise<CachedModule> {
+    const stat = statSync(filePath);
+    const mtimeMs = stat.mtimeMs;
+
+    const cached = this.moduleCache.get(filePath);
+    if (cached && cached.mtimeMs === mtimeMs) {
+      return cached;
+    }
+
+    // Cache-bust Bun's module cache by appending mtime as a query param.
+    const mod = (await import(`${filePath}?t=${mtimeMs}`)) as Record<
+      string,
+      unknown
+    >;
+
+    const handlers: Partial<Record<HttpMethod, RouteHandler>> = {};
+    for (const method of HTTP_METHODS) {
+      if (typeof mod[method] === "function") {
+        handlers[method] = mod[method] as RouteHandler;
+      }
+    }
+
+    const description =
+      typeof mod.description === "string" ? mod.description : undefined;
+
+    const entry: CachedModule = { handlers, description, mtimeMs };
+    this.moduleCache.set(filePath, entry);
+
+    log.info(
+      { filePath, methods: Object.keys(handlers), description },
+      "Loaded user route handler",
+    );
+
+    return entry;
+  }
+
+  /**
+   * Execute a handler function with a per-request timeout and error boundary.
+   */
+  private async executeHandler(
+    handler: RouteHandler,
+    request: Request,
+    routePath: string,
+  ): Promise<Response> {
+    try {
+      const result = await Promise.race([
+        Promise.resolve(handler(request)),
+        new Promise<never>((_, reject) =>
+          setTimeout(
+            () => reject(new Error("Handler timed out")),
+            this.handlerTimeoutMs,
+          ),
+        ),
+      ]);
+      return result;
+    } catch (err) {
+      if (err instanceof Error && err.message === "Handler timed out") {
+        log.error(
+          { routePath, timeoutMs: this.handlerTimeoutMs },
+          "User route handler timed out",
+        );
+        return httpError(
+          "SERVICE_UNAVAILABLE",
+          `Route handler for /x/${routePath} timed out after ${this.handlerTimeoutMs}ms`,
+          504,
+        );
+      }
+
+      log.error({ err, routePath }, "User route handler threw an error");
+      const message =
+        err instanceof Error ? err.message : "Internal server error";
+      return httpError("INTERNAL_ERROR", message, 500);
+    }
+  }
+}

package/src/runtime/routes/user-routes.ts

@@ -0,0 +1,41 @@
+/**
+ * Route definitions for user-defined endpoints under `/x/*`.
+ *
+ * Registers a single catch-all route that delegates to the
+ * UserRouteDispatcher for file-based dispatch from
+ * `$VELLUM_WORKSPACE_DIR/routes/`.
+ */
+
+import type { RouteDefinition } from "../http-router.js";
+import { UserRouteDispatcher } from "./user-route-dispatcher.js";
+
+const dispatcher = new UserRouteDispatcher();
+
+/**
+ * HTTP methods supported by user-defined route handlers.
+ *
+ * Each method gets its own route definition so the HttpRouter can match
+ * on method before dispatching. The catch-all `x/:path*` pattern ensures
+ * all sub-paths are captured regardless of depth.
+ */
+const METHODS = [
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "HEAD",
+  "OPTIONS",
+] as const;
+
+export function userRouteDefinitions(): RouteDefinition[] {
+  return METHODS.map((method) => ({
+    endpoint: "x/:path*",
+    method,
+    policyKey: "x",
+    summary: `User-defined ${method} route`,
+    description: `Dispatches ${method} requests to user-defined handler files in the workspace routes directory.`,
+    tags: ["user-routes"],
+    handler: ({ params, req }) => dispatcher.dispatch(params.path, req),
+  }));
+}

package/src/runtime/routes/workspace-routes.ts

@@ -1,7 +1,6 @@
 /**
  * Route handlers for workspace file browsing and content serving.
  *
- * WARNING: Workspace contents are included in diagnostic log exports.
  * Do not store secrets here — use the credential store or protected/ directory.
  */
 import {

package/src/schedule/schedule-store.ts

@@ -36,6 +36,7 @@ export interface ScheduleJob {
   routingIntent: RoutingIntent;
   routingHints: Record<string, unknown>;
   quiet: boolean;
+  reuseConversation: boolean;
   status: ScheduleStatus;
   createdAt: number;
   updatedAt: number;
@@ -93,6 +94,7 @@ export function createSchedule(params: {
   routingIntent?: RoutingIntent;
   routingHints?: Record<string, unknown>;
   quiet?: boolean;
+  reuseConversation?: boolean;
 }): ScheduleJob {
   const expression = params.expression ?? params.cronExpression ?? null;
   const isOneShot = expression == null;
@@ -121,6 +123,7 @@ export function createSchedule(params: {
   const routingIntent = params.routingIntent ?? "all_channels";
   const routingHints = params.routingHints ?? {};
   const quiet = params.quiet ?? false;
+  const reuseConversation = params.reuseConversation ?? false;
 
   let nextRunAt: number;
   if (isOneShot) {
@@ -148,6 +151,7 @@ export function createSchedule(params: {
     routingIntent,
     routingHintsJson: JSON.stringify(routingHints),
     quiet,
+    reuseConversation,
     status: "active" as ScheduleStatus,
     createdAt: now,
     updatedAt: now,
@@ -220,6 +224,7 @@ export function updateSchedule(
     routingIntent?: RoutingIntent;
     routingHints?: Record<string, unknown>;
     quiet?: boolean;
+    reuseConversation?: boolean;
   },
 ): ScheduleJob | null {
   const db = getDb();
@@ -275,6 +280,8 @@ export function updateSchedule(
   if (updates.routingHints !== undefined)
     set.routingHintsJson = JSON.stringify(updates.routingHints);
   if (updates.quiet !== undefined) set.quiet = updates.quiet;
+  if (updates.reuseConversation !== undefined)
+    set.reuseConversation = updates.reuseConversation;
 
   // Recompute nextRunAt if schedule timing may have changed (only for recurring)
   if (
@@ -563,6 +570,28 @@ export function completeScheduleRun(
   }
 }
 
+/**
+ * Return the conversation ID from the most recent successful run
+ * for a given schedule, or null if none exists.
+ */
+export function getLastScheduleConversationId(jobId: string): string | null {
+  const db = getDb();
+  const row = db
+    .select({ conversationId: scheduleRuns.conversationId })
+    .from(scheduleRuns)
+    .where(
+      and(
+        eq(scheduleRuns.jobId, jobId),
+        eq(scheduleRuns.status, "ok"),
+        sql`${scheduleRuns.conversationId} IS NOT NULL`,
+      ),
+    )
+    .orderBy(desc(scheduleRuns.createdAt))
+    .limit(1)
+    .get();
+  return row?.conversationId ?? null;
+}
+
 export function getScheduleRuns(jobId: string, limit?: number): ScheduleRun[] {
   const db = getDb();
   const rows = db
@@ -757,6 +786,7 @@ function parseJobRow(row: typeof scheduleJobs.$inferSelect): ScheduleJob {
     routingIntent: (row.routingIntent ?? "all_channels") as RoutingIntent,
     routingHints: safeParseJson(row.routingHintsJson),
     quiet: row.quiet ?? false,
+    reuseConversation: row.reuseConversation ?? false,
     status: (row.status ?? "active") as ScheduleStatus,
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,

package/src/schedule/scheduler.ts

@@ -1,4 +1,5 @@
 import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
+import { getConversation } from "../memory/conversation-crud.js";
 import { invalidateAssistantInferredItemsForConversation } from "../memory/task-memory-cleanup.js";
 import { runSequencesOnce } from "../sequence/engine.js";
 import { getLogger } from "../util/logger.js";
@@ -14,6 +15,7 @@ import {
   completeScheduleRun,
   createScheduleRun,
   failOneShot,
+  getLastScheduleConversationId,
   type RoutingIntent,
 } from "./schedule-store.js";
 
@@ -240,6 +242,7 @@ async function runScheduleOnce(
         );
         // Create a fallback conversation for the schedule run record
         const fallbackConversation = bootstrapConversation({
+          conversationType: "scheduled",
           source: "schedule",
           scheduleJobId: job.id,
           groupId: "system:scheduled",
@@ -258,19 +261,36 @@ async function runScheduleOnce(
       continue;
     }
 
-    const conversation = bootstrapConversation({
-      source: "schedule",
-      scheduleJobId: job.id,
-      groupId: "system:scheduled",
-      origin: "schedule",
-      systemHint: isOneShot ? `Reminder: ${job.name}` : `Schedule: ${job.name}`,
-    });
+    // Reuse the conversation from the last successful run when the flag is set
+    // and a prior conversation still exists; otherwise bootstrap a new one.
+    let conversationId: string | null = null;
+    let conversationReused = false;
+    if (job.reuseConversation && !isOneShot) {
+      const lastId = getLastScheduleConversationId(job.id);
+      if (lastId && getConversation(lastId)) {
+        conversationId = lastId;
+        conversationReused = true;
+      }
+    }
+    if (!conversationId) {
+      const conversation = bootstrapConversation({
+        conversationType: "scheduled",
+        source: "schedule",
+        scheduleJobId: job.id,
+        groupId: "system:scheduled",
+        origin: "schedule",
+        systemHint: isOneShot
+          ? `Reminder: ${job.name}`
+          : `Schedule: ${job.name}`,
+      });
+      conversationId = conversation.id;
+    }
     onScheduleConversationCreated?.({
-      conversationId: conversation.id,
+      conversationId,
       scheduleJobId: job.id,
       title: job.name,
     });
-    const runId = createScheduleRun(job.id, conversation.id);
+    const runId = createScheduleRun(job.id, conversationId);
     const isRruleSetMsg =
       job.syntax === "rrule" &&
       job.expression != null &&
@@ -285,11 +305,11 @@ async function runScheduleOnce(
           expression: job.expression,
           isRruleSet: isRruleSetMsg,
           isOneShot,
-          conversationId: conversation.id,
+          conversationId,
         },
         isOneShot ? "Executing one-shot schedule" : "Executing schedule",
       );
-      await processMessage(conversation.id, job.message, {
+      await processMessage(conversationId, job.message, {
         trustClass: "guardian",
       });
       completeScheduleRun(runId, { status: "ok" });
@@ -317,13 +337,20 @@ async function runScheduleOnce(
       completeScheduleRun(runId, { status: "error", error: message });
       if (isOneShot) failOneShot(job.id);
 
-      try {
-        invalidateAssistantInferredItemsForConversation(conversation.id);
-      } catch (cleanupErr) {
-        log.warn(
-          { err: cleanupErr, conversationId: conversation.id },
-          "Failed to invalidate assistant-inferred memory items",
-        );
+      // Only skip invalidation when the conversation was *actually* reused,
+      // i.e. it contains prior successful context worth preserving. When
+      // reuseConversation is true but no prior conversation existed (first run
+      // or deleted), the conversation is brand-new and should be invalidated
+      // like any other failed conversation.
+      if (!conversationReused) {
+        try {
+          invalidateAssistantInferredItemsForConversation(conversationId);
+        } catch (cleanupErr) {
+          log.warn(
+            { err: cleanupErr, conversationId },
+            "Failed to invalidate assistant-inferred memory items",
+          );
+        }
       }
     }
   }

package/src/skills/catalog-install.ts

@@ -14,10 +14,10 @@ import { dirname, join, posix, resolve, sep } from "node:path";
 import { gunzipSync } from "node:zlib";
 
 import { getPlatformBaseUrl } from "../config/env.js";
+import { deleteSkillCapabilityNode } from "../memory/graph/capability-seed.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceSkillsDir, readPlatformToken } from "../util/platform.js";
 import { computeSkillHash, writeInstallMeta } from "./install-meta.js";
-import { deleteSkillCapabilityMemory } from "./skill-memory.js";
 
 const log = getLogger("catalog-install");
 
@@ -264,7 +264,7 @@ export function uninstallSkillLocally(skillId: string): void {
 
   rmSync(skillDir, { recursive: true, force: true });
   removeSkillsIndexEntry(skillId);
-  deleteSkillCapabilityMemory(skillId);
+  deleteSkillCapabilityNode(skillId);
 }
 
 export async function installSkillLocally(
@@ -392,6 +392,14 @@ export async function autoInstallFromCatalog(
     return false;
   }
 
+  // If the skill already exists on disk (stale index), re-index it instead
+  // of attempting a fresh install that would fail.
+  const skillDir = join(getWorkspaceSkillsDir(), skillId);
+  if (existsSync(join(skillDir, "SKILL.md"))) {
+    upsertSkillsIndex(skillId);
+    return true;
+  }
+
   // installSkillLocally handles dependency installation and SKILLS.md indexing.
   await installSkillLocally(skillId, entry, false);
 

package/src/skills/managed-store.ts

@@ -11,10 +11,10 @@ import { dirname, join } from "node:path";
 
 import { stringify as stringifyYaml } from "yaml";
 
+import { deleteSkillCapabilityNode } from "../memory/graph/capability-seed.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceSkillsDir } from "../util/platform.js";
 import { writeInstallMeta } from "./install-meta.js";
-import { deleteSkillCapabilityMemory } from "./skill-memory.js";
 
 const log = getLogger("managed-store");
 
@@ -319,7 +319,7 @@ export function deleteManagedSkill(
   }
 
   rmSync(skillDir, { recursive: true });
-  deleteSkillCapabilityMemory(id);
+  deleteSkillCapabilityNode(id);
   log.info({ id, path: skillDir }, "Deleted managed skill");
 
   let indexUpdated = false;