@vellumai/assistant 0.8.4 → 0.8.6

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

@@ -8,6 +8,7 @@ import { desc, eq, inArray } from "drizzle-orm";
 import { z } from "zod";
 
 import { getAcpSessionManager } from "../../acp/index.js";
+import { prepareAgentEnv } from "../../acp/prepare-agent-env.js";
 import { resolveAcpAgent } from "../../acp/resolve-agent.js";
 import type { AcpSessionState } from "../../acp/types.js";
 import { getDb } from "../../memory/db-connection.js";
@@ -81,6 +82,12 @@ async function spawnSession({ body }: RouteHandlerArgs) {
     }
   }
 
+  // Inject required env vars and preflight via the shared helper. See
+  // `acp/prepare-agent-env.ts` for the full rationale; calling it here
+  // keeps the HTTP route in lockstep with the skill-tool spawn path
+  // (`tools/acp/spawn.ts`).
+  const agentConfig = await prepareAgentEnv(resolved.agent);
+
   log.info(
     { agent, task: task.slice(0, 100), conversationId },
     "ACP spawn request received",
@@ -89,7 +96,7 @@ async function spawnSession({ body }: RouteHandlerArgs) {
   const manager = getAcpSessionManager();
   const { acpSessionId, protocolSessionId } = await manager.spawn(
     agent,
-    resolved.agent,
+    agentConfig,
     task,
     cwd,
     conversationId,

package/src/runtime/routes/app-management-routes.ts

@@ -786,7 +786,17 @@ export const ROUTES: RouteDefinition[] = [
       },
     ],
     responseBody: z.object({
-      apps: z.array(z.unknown()).describe("Array of app summary objects"),
+      apps: z.array(
+        z.object({
+          id: z.string(),
+          name: z.string(),
+          description: z.string().optional(),
+          icon: z.string().optional(),
+          createdAt: z.number(),
+          version: z.string(),
+          contentId: z.string(),
+        }),
+      ),
     }),
   },
   {
@@ -802,6 +812,21 @@ export const ROUTES: RouteDefinition[] = [
     requestBody: z.object({
       filePath: z.string().describe("Absolute path to the .vbundle file"),
     }),
+    responseBody: z.object({
+      manifest: z.object({}).passthrough(),
+      scanResult: z.object({
+        passed: z.boolean(),
+        blocked: z.array(z.string()),
+        warnings: z.array(z.string()),
+      }),
+      signatureResult: z.object({
+        trustTier: z.string(),
+        signerKeyId: z.string().optional(),
+        signerDisplayName: z.string().optional(),
+        signerAccount: z.string().optional(),
+      }),
+      bundleSizeBytes: z.number(),
+    }),
   },
   {
     operationId: "apps_shared_list",
@@ -813,7 +838,23 @@ export const ROUTES: RouteDefinition[] = [
     description: "Return all apps available via cloud share links.",
     tags: ["apps"],
     responseBody: z.object({
-      apps: z.array(z.unknown()).describe("Array of shared app objects"),
+      apps: z.array(
+        z.object({
+          uuid: z.string(),
+          name: z.string(),
+          description: z.string().optional(),
+          icon: z.string().optional(),
+          preview: z.string().optional(),
+          entry: z.string(),
+          trustTier: z.string(),
+          signerDisplayName: z.string().optional(),
+          bundleSizeBytes: z.number(),
+          installedAt: z.string(),
+          version: z.string().optional(),
+          contentId: z.string().optional(),
+          updateAvailable: z.boolean().optional(),
+        }),
+      ),
     }),
   },
   {
@@ -828,6 +869,11 @@ export const ROUTES: RouteDefinition[] = [
     requestBody: z.object({
       uuid: z.string().describe("UUID of the shared app to fork"),
     }),
+    responseBody: z.object({
+      success: z.literal(true),
+      appId: z.string(),
+      name: z.string(),
+    }),
   },
   {
     operationId: "apps_gallery_install",
@@ -839,6 +885,11 @@ export const ROUTES: RouteDefinition[] = [
     description: "Install an app from the built-in gallery by its ID.",
     tags: ["apps"],
     requestBody: z.object({ galleryAppId: z.string() }),
+    responseBody: z.object({
+      success: z.literal(true),
+      appId: z.string(),
+      name: z.string(),
+    }),
   },
   {
     operationId: "apps_gallery_list",
@@ -850,7 +901,28 @@ export const ROUTES: RouteDefinition[] = [
     description: "Return the built-in app gallery catalog.",
     tags: ["apps"],
     responseBody: z.object({
-      gallery: z.array(z.unknown()).describe("Gallery app entries"),
+      gallery: z.object({
+        version: z.number(),
+        updatedAt: z.string(),
+        categories: z.array(
+          z.object({
+            id: z.string(),
+            name: z.string(),
+            icon: z.string(),
+          }),
+        ),
+        apps: z.array(
+          z.object({
+            id: z.string(),
+            name: z.string(),
+            description: z.string(),
+            icon: z.string(),
+            category: z.string(),
+            version: z.string(),
+            featured: z.boolean().optional(),
+          }),
+        ),
+      }),
     }),
   },
   {
@@ -897,6 +969,12 @@ export const ROUTES: RouteDefinition[] = [
       keyId: z.string().optional(),
       publicKey: z.string().optional(),
     }),
+    responseBody: z.object({
+      signed: z.boolean().optional(),
+      signatureJson: z.object({}).passthrough().optional(),
+      payload: z.string().optional(),
+      message: z.string().optional(),
+    }),
   },
   {
     operationId: "apps_signing_identity",
@@ -908,6 +986,7 @@ export const ROUTES: RouteDefinition[] = [
     description:
       "Return signing identity info. Signing is managed client-side over HTTP.",
     tags: ["apps"],
+    responseBody: z.object({ message: z.string() }),
   },
 
   // Parameterized `apps/:id/*` routes — must follow all literal routes.
@@ -927,6 +1006,10 @@ export const ROUTES: RouteDefinition[] = [
         type: "string",
       },
     ],
+    responseBody: z.object({
+      success: z.boolean(),
+      result: z.unknown(),
+    }),
   },
   {
     operationId: "apps_data_mutate",
@@ -943,6 +1026,10 @@ export const ROUTES: RouteDefinition[] = [
       recordId: z.string(),
       data: z.object({}).passthrough(),
     }),
+    responseBody: z.object({
+      success: z.boolean(),
+      result: z.unknown(),
+    }),
   },
   {
     operationId: "apps_open",
@@ -969,6 +1056,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Delete an app",
     description: "Permanently remove an app and its data.",
     tags: ["apps"],
+    responseBody: z.object({ success: z.boolean() }),
   },
   {
     operationId: "apps_preview_get",
@@ -979,6 +1067,10 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Get app preview",
     description: "Return the preview image or HTML for an app.",
     tags: ["apps"],
+    responseBody: z.object({
+      appId: z.string(),
+      preview: z.string().nullable(),
+    }),
   },
   {
     operationId: "apps_preview_update",
@@ -992,6 +1084,10 @@ export const ROUTES: RouteDefinition[] = [
     requestBody: z.object({
       preview: z.string().describe("Base64-encoded image or HTML string"),
     }),
+    responseBody: z.object({
+      success: z.boolean(),
+      appId: z.string(),
+    }),
   },
   {
     operationId: "apps_history",
@@ -1005,7 +1101,13 @@ export const ROUTES: RouteDefinition[] = [
     queryParams: [{ name: "limit", type: "number" }],
     responseBody: z.object({
       appId: z.string(),
-      versions: z.array(z.unknown()),
+      versions: z.array(
+        z.object({
+          commitHash: z.string(),
+          message: z.string(),
+          timestamp: z.number(),
+        }),
+      ),
     }),
   },
   {
@@ -1021,6 +1123,10 @@ export const ROUTES: RouteDefinition[] = [
       { name: "fromCommit", type: "string", required: true },
       { name: "toCommit", type: "string" },
     ],
+    responseBody: z.object({
+      appId: z.string(),
+      diff: z.string(),
+    }),
   },
   {
     operationId: "apps_restore",
@@ -1032,6 +1138,7 @@ export const ROUTES: RouteDefinition[] = [
     description: "Restore an app to a previous git commit.",
     tags: ["apps"],
     requestBody: z.object({ commitHash: z.string() }),
+    responseBody: z.object({ success: z.boolean() }),
   },
   {
     operationId: "apps_bundle",

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

@@ -40,7 +40,7 @@ function handleGetCharacterComponents() {
   return getCharacterComponents();
 }
 
-function handleRenderFromTraits({ body }: RouteHandlerArgs) {
+function handleRenderFromTraits({ body, headers }: RouteHandlerArgs) {
   const traits = body as CharacterTraits | undefined;
 
   if (
@@ -69,11 +69,11 @@ function handleRenderFromTraits({ body }: RouteHandlerArgs) {
   }
 
   updateIdentityAvatarSection(null, log);
-  publishAvatarChanged();
+  publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
   return { ok: true };
 }
 
-async function handleGenerateAvatar({ body }: RouteHandlerArgs) {
+async function handleGenerateAvatar({ body, headers }: RouteHandlerArgs) {
   const description = (body as Record<string, unknown>)?.description as
     | string
     | undefined;
@@ -109,11 +109,11 @@ async function handleGenerateAvatar({ body }: RouteHandlerArgs) {
   }
 
   updateIdentityAvatarSection(null, log);
-  publishAvatarChanged();
+  publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
   return { ok: true, message: result.content };
 }
 
-function handleSetAvatar({ body }: RouteHandlerArgs) {
+function handleSetAvatar({ body, headers }: RouteHandlerArgs) {
   const imagePath = (body as Record<string, unknown>)?.imagePath as
     | string
     | undefined;
@@ -142,11 +142,11 @@ function handleSetAvatar({ body }: RouteHandlerArgs) {
   copyFileSync(normalized, avatarPath);
 
   updateIdentityAvatarSection(null, log);
-  publishAvatarChanged();
+  publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
   return { ok: true };
 }
 
-function handleRemoveAvatar(_args: RouteHandlerArgs) {
+function handleRemoveAvatar({ headers }: RouteHandlerArgs) {
   const avatarPath = getAvatarImagePath();
 
   if (!existsSync(avatarPath)) {
@@ -172,7 +172,7 @@ function handleRemoveAvatar(_args: RouteHandlerArgs) {
     "Default character avatar (no custom image set)",
     log,
   );
-  publishAvatarChanged();
+  publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
   return { ok: true, hadAvatar: true };
 }
 
@@ -286,8 +286,8 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "notify_avatar_updated",
     endpoint: "avatar/notify-updated",
     method: "POST",
-    handler: () => {
-      publishAvatarChanged();
+    handler: ({ headers }: RouteHandlerArgs) => {
+      publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
       return { ok: true };
     },
     summary: "Notify avatar updated",

package/src/runtime/routes/background-wake-routes.ts

@@ -0,0 +1,356 @@
+import { z } from "zod";
+
+import {
+  type BackgroundWakeIntent,
+  computeNextBackgroundWakeIntent,
+} from "../../background-wake/next-wake.js";
+import type { BackgroundWakeRuntime } from "../../background-wake/runtime-registry.js";
+import { getBackgroundWakeRuntime } from "../../background-wake/runtime-registry.js";
+import { getLogger } from "../../util/logger.js";
+import { BadRequestError, ServiceUnavailableError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+const PREPARE_SLEEP_DEFER_WINDOW_MS = 60_000;
+const HEARTBEAT_DUE_TOLERANCE_MS = 1_000;
+const MIN_DRAIN_START_BUDGET_MS = 5_000;
+const LEASE_RENEW_INTERVAL_MS = 120_000;
+const log = getLogger("background-wake-routes");
+
+class DrainDeadlineElapsedError extends Error {
+  constructor() {
+    super("background wake lease deadline elapsed before starting work");
+    this.name = "DrainDeadlineElapsedError";
+  }
+}
+
+type RenewWakeLease = (leaseId: string) => Promise<unknown>;
+type CompleteWakeLease = (args: {
+  leaseId: string;
+  status: "completed" | "failed" | "expired";
+  error?: string;
+  nextIntent?: BackgroundWakeIntent | null;
+}) => Promise<unknown>;
+
+let computeWakeIntent = computeNextBackgroundWakeIntent;
+let renewWakeLease: RenewWakeLease = defaultRenewWakeLease;
+let completeWakeLease: CompleteWakeLease = defaultCompleteWakeLease;
+const activeDrainLeases = new Set<string>();
+const activeDrainPromises = new Set<Promise<void>>();
+const timestampInputSchema = z.union([z.number(), z.string()]);
+
+const wakeIntentSchema = z
+  .object({
+    nextWakeAt: z.number(),
+    actualNextDueAt: z.number(),
+    reason: z.enum(["heartbeat", "schedule", "mixed"]),
+    sourceGeneration: z.string(),
+    computedAt: z.number(),
+    sourcePayload: z.record(z.string(), z.unknown()),
+  })
+  .nullable();
+
+const normalizedDrainDueRequestSchema = z.object({
+  leaseId: z.string().min(1),
+  reason: z.string().min(1),
+  sourceGeneration: z.string().min(1),
+  startedAt: z.number(),
+  deadlineAt: z.number(),
+});
+
+const drainDueRequestSchema = z.union([
+  z.object({
+    leaseId: z.string().min(1),
+    reason: z.string().min(1),
+    sourceGeneration: z.string().min(1),
+    startedAt: timestampInputSchema,
+    deadlineAt: timestampInputSchema,
+  }),
+  z.object({
+    lease_id: z.string().min(1),
+    reason: z.string().min(1),
+    source_generation: z.string().min(1),
+    started_at: timestampInputSchema,
+    deadline_at: timestampInputSchema,
+  }),
+]);
+
+function normalizeDrainDueBody(body: Record<string, unknown>) {
+  return {
+    leaseId: body.leaseId ?? body.lease_id,
+    reason: body.reason,
+    sourceGeneration: body.sourceGeneration ?? body.source_generation,
+    startedAt: normalizeTimestamp(body.startedAt ?? body.started_at),
+    deadlineAt: normalizeTimestamp(body.deadlineAt ?? body.deadline_at),
+  };
+}
+
+function normalizeTimestamp(value: unknown): unknown {
+  if (typeof value === "number") return value;
+  if (typeof value !== "string") return value;
+  const numeric = Number(value);
+  if (Number.isFinite(numeric)) return numeric;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : value;
+}
+
+type DrainDueRequest = z.infer<typeof normalizedDrainDueRequestSchema>;
+function parseDrainDueBody(body: Record<string, unknown>): DrainDueRequest {
+  const parsed = normalizedDrainDueRequestSchema.safeParse(
+    normalizeDrainDueBody(body),
+  );
+  if (!parsed.success) {
+    throw new BadRequestError(
+      "leaseId, reason, sourceGeneration, startedAt, and deadlineAt are required",
+    );
+  }
+  return parsed.data;
+}
+
+async function defaultRenewWakeLease(leaseId: string): Promise<unknown> {
+  const { renewBackgroundWakeLease } =
+    await import("../../background-wake/platform-client.js");
+  return renewBackgroundWakeLease(leaseId);
+}
+
+async function defaultCompleteWakeLease(
+  args: Parameters<CompleteWakeLease>[0],
+): Promise<unknown> {
+  const { completeBackgroundWakeLease } =
+    await import("../../background-wake/platform-client.js");
+  return completeBackgroundWakeLease(args);
+}
+
+function handleGetIntent() {
+  return { intent: computeWakeIntent() };
+}
+
+function handlePrepareSleep() {
+  const now = Date.now();
+  const intent = computeWakeIntent(now);
+  return {
+    intent,
+    deferSleep:
+      intent != null &&
+      intent.nextWakeAt <= now + PREPARE_SLEEP_DEFER_WINDOW_MS,
+  };
+}
+
+async function handleDrainDue(body: Record<string, unknown>) {
+  const request = parseDrainDueBody(body);
+  const runtime = getBackgroundWakeRuntime();
+  if (!runtime) {
+    throw new ServiceUnavailableError(
+      "Background wake runtime is not registered",
+    );
+  }
+
+  if (!activeDrainLeases.has(request.leaseId)) {
+    activeDrainLeases.add(request.leaseId);
+    const drainPromise = runDrainDueLease(request, runtime);
+    activeDrainPromises.add(drainPromise);
+    void drainPromise.finally(() => activeDrainPromises.delete(drainPromise));
+  }
+
+  return {
+    accepted: true,
+    leaseId: request.leaseId,
+    reason: request.reason,
+    sourceGeneration: request.sourceGeneration,
+    startedAt: request.startedAt,
+    deadlineAt: request.deadlineAt,
+  };
+}
+
+async function runDrainDueLease(
+  request: DrainDueRequest,
+  runtime: BackgroundWakeRuntime,
+): Promise<void> {
+  let renewTimer: ReturnType<typeof setInterval> | undefined;
+  try {
+    renewTimer = setInterval(() => {
+      void renewWakeLease(request.leaseId).catch(() => {});
+    }, LEASE_RENEW_INTERVAL_MS);
+    renewTimer.unref?.();
+
+    assertDrainCanStart(request.deadlineAt);
+    const result = await performDrainDue(request, runtime);
+    await reportLeaseCompletion({
+      leaseId: request.leaseId,
+      status: "completed",
+      nextIntent: result.nextIntent,
+    });
+  } catch (error) {
+    await reportLeaseCompletion({
+      leaseId: request.leaseId,
+      status: completionStatusForError(error),
+      error: error instanceof Error ? error.message : String(error),
+      nextIntent: computeWakeIntent(),
+    });
+  } finally {
+    if (renewTimer) clearInterval(renewTimer);
+    activeDrainLeases.delete(request.leaseId);
+  }
+}
+
+async function reportLeaseCompletion(
+  args: Parameters<CompleteWakeLease>[0],
+): Promise<void> {
+  try {
+    await completeWakeLease(args);
+  } catch (err) {
+    log.warn(
+      { err, leaseId: args.leaseId, status: args.status },
+      "Failed to report background wake lease completion",
+    );
+  }
+}
+
+async function performDrainDue(
+  request: DrainDueRequest,
+  runtime: BackgroundWakeRuntime,
+) {
+  const now = Date.now();
+  const currentIntent = computeWakeIntent(now);
+  const heartbeatDue = isHeartbeatTimerDue(runtime.heartbeat.nextRunAt, now);
+  const schedulerDue =
+    heartbeatDue ||
+    reasonIncludesSource(request.reason, "schedule") ||
+    intentHasDueSource(currentIntent, "schedule", now);
+
+  if (heartbeatDue) {
+    if (hasStartBudget(request.deadlineAt)) {
+      await runtime.heartbeat.runManagedWakeIfDue({
+        now,
+        toleranceMs: HEARTBEAT_DUE_TOLERANCE_MS,
+        scheduledFor: request.startedAt,
+      });
+    }
+  }
+
+  if (schedulerDue) {
+    await runtime.scheduler.runDueWorkOnce({
+      deadlineAt: request.deadlineAt,
+      minStartBudgetMs: MIN_DRAIN_START_BUDGET_MS,
+      includeStillPending: true,
+    });
+  }
+
+  const nextIntent = computeWakeIntent();
+
+  return {
+    nextIntent,
+  };
+}
+
+function assertDrainCanStart(deadlineAt: number): void {
+  if (deadlineAt <= Date.now()) {
+    throw new DrainDeadlineElapsedError();
+  }
+}
+
+function completionStatusForError(error: unknown): "failed" | "expired" {
+  return error instanceof DrainDeadlineElapsedError ? "expired" : "failed";
+}
+
+function reasonIncludesSource(
+  reason: string,
+  source: "heartbeat" | "schedule",
+): boolean {
+  return reason === "mixed" || reason === source;
+}
+
+function isHeartbeatTimerDue(nextRunAt: number | null, now: number): boolean {
+  return nextRunAt != null && nextRunAt <= now + HEARTBEAT_DUE_TOLERANCE_MS;
+}
+
+function intentHasDueSource(
+  intent: BackgroundWakeIntent | null,
+  source: "heartbeat" | "schedule",
+  now: number,
+): boolean {
+  return (
+    intent != null &&
+    intent.actualNextDueAt <= now + HEARTBEAT_DUE_TOLERANCE_MS &&
+    reasonIncludesSource(intent.reason, source)
+  );
+}
+
+function hasStartBudget(deadlineAt: number): boolean {
+  return deadlineAt - Date.now() >= MIN_DRAIN_START_BUDGET_MS;
+}
+
+/** @internal Test helper for route-only tests. */
+export function setBackgroundWakeIntentComputerForTest(
+  nextCompute: typeof computeNextBackgroundWakeIntent | null,
+): void {
+  computeWakeIntent = nextCompute ?? computeNextBackgroundWakeIntent;
+}
+
+/** @internal Test helper for route-only tests. */
+export function setBackgroundWakeLeaseClientForTest(
+  nextClient: {
+    renew: RenewWakeLease;
+    complete: CompleteWakeLease;
+  } | null,
+): void {
+  renewWakeLease = nextClient?.renew ?? defaultRenewWakeLease;
+  completeWakeLease = nextClient?.complete ?? defaultCompleteWakeLease;
+}
+
+/** @internal Test helper for route-only tests. */
+export async function flushBackgroundWakeDrainsForTest(): Promise<void> {
+  while (activeDrainPromises.size > 0) {
+    await Promise.allSettled([...activeDrainPromises]);
+  }
+}
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "getBackgroundWakeIntent",
+    endpoint: "background-wake/intent",
+    method: "GET",
+    policyKey: "background-wake",
+    summary: "Get background wake intent",
+    description: "Return the current computed background wake intent.",
+    tags: ["background-wake"],
+    responseBody: z.object({
+      intent: wakeIntentSchema,
+    }),
+    handler: () => handleGetIntent(),
+  },
+  {
+    operationId: "prepareBackgroundWakeSleep",
+    endpoint: "background-wake/prepare-sleep",
+    method: "POST",
+    policyKey: "background-wake",
+    summary: "Prepare for assistant sleep",
+    description:
+      "Return the current background wake intent and whether sleep should be deferred.",
+    tags: ["background-wake"],
+    responseBody: z.object({
+      intent: wakeIntentSchema,
+      deferSleep: z.boolean(),
+    }),
+    handler: () => handlePrepareSleep(),
+  },
+  {
+    operationId: "drainDueBackgroundWake",
+    endpoint: "background-wake/drain-due",
+    method: "POST",
+    policyKey: "background-wake",
+    summary: "Drain due background wake work",
+    description:
+      "Run due heartbeat and scheduler work for a background wake lease.",
+    tags: ["background-wake"],
+    requestBody: drainDueRequestSchema,
+    responseBody: z.object({
+      accepted: z.boolean(),
+      leaseId: z.string(),
+      reason: z.string(),
+      sourceGeneration: z.string(),
+      startedAt: z.number(),
+      deadlineAt: z.number(),
+    }),
+    handler: ({ body }: RouteHandlerArgs) => handleDrainDue(body ?? {}),
+  },
+];