@vellumai/assistant 0.4.56 → 0.5.0

package/src/runtime/routes/identity-intro-cache.ts

@@ -0,0 +1,105 @@
+/**
+ * Caching layer for the LLM-generated identity intro text.
+ *
+ * The intro (a short identity tagline) is generated via the
+ * /v1/btw endpoint and displayed on the Identity panel. To avoid redundant LLM
+ * calls, we cache the result for 4 hours with content-hash-based invalidation:
+ * when USER.md, IDENTITY.md, or SOUL.md change, the cache is busted.
+ *
+ * Storage uses the existing `memory_checkpoints` table (simple key-value store).
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+
+import {
+  getMemoryCheckpoint,
+  setMemoryCheckpoint,
+} from "../../memory/checkpoints.js";
+import { getWorkspacePromptPath } from "../../util/platform.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
+
+const CHECKPOINT_KEY_TEXT = "identity:intro:text";
+const CHECKPOINT_KEY_HASH = "identity:intro:content_hash";
+const CHECKPOINT_KEY_TIMESTAMP = "identity:intro:cached_at";
+
+/** Workspace files whose content influences the identity intro. */
+const IDENTITY_FILES = ["USER.md", "IDENTITY.md", "SOUL.md"] as const;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Read a workspace prompt file, returning empty string if missing. */
+function readWorkspaceFile(name: string): string {
+  try {
+    const path = getWorkspacePromptPath(name);
+    if (!existsSync(path)) return "";
+    return readFileSync(path, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+/** Compute a SHA-256 hex hash of the concatenated identity file contents. */
+export function computeIdentityContentHash(): string {
+  const combined = IDENTITY_FILES.map(readWorkspaceFile).join("\n---\n");
+  return createHash("sha256").update(combined).digest("hex");
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface CachedIntro {
+  text: string;
+}
+
+/**
+ * Retrieve the cached identity intro if it exists, is within the TTL window,
+ * and the identity files have not changed since it was generated.
+ *
+ * Returns `null` when the cache is missing, expired, or invalidated.
+ */
+export function getCachedIntro(): CachedIntro | null {
+  try {
+    const text = getMemoryCheckpoint(CHECKPOINT_KEY_TEXT);
+    const hash = getMemoryCheckpoint(CHECKPOINT_KEY_HASH);
+    const timestampStr = getMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP);
+
+    if (!text || !hash || !timestampStr) return null;
+
+    // TTL check
+    const cachedAt = Number(timestampStr);
+    if (isNaN(cachedAt) || Date.now() - cachedAt > CACHE_TTL_MS) return null;
+
+    // Content-hash check — bust cache when identity files change
+    const currentHash = computeIdentityContentHash();
+    if (currentHash !== hash) return null;
+
+    return { text };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Store the generated identity intro text in the cache along with
+ * the current content hash and timestamp.
+ */
+export function setCachedIntro(text: string): void {
+  try {
+    const hash = computeIdentityContentHash();
+    const now = String(Date.now());
+    setMemoryCheckpoint(CHECKPOINT_KEY_TEXT, text);
+    setMemoryCheckpoint(CHECKPOINT_KEY_HASH, hash);
+    setMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP, now);
+  } catch {
+    // Cache write failure is non-fatal — next request will regenerate.
+  }
+}

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

@@ -11,6 +11,7 @@ import { getBaseDataDir } from "../../config/env-registry.js";
 import { getWorkspacePromptPath, readLockfile } from "../../util/platform.js";
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
+import { getCachedIntro } from "./identity-intro-cache.js";
 
 interface DiskSpaceInfo {
   path: string;
@@ -233,6 +234,51 @@ export function handleGetIdentity(): Response {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Identity intro cache
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the `## Identity Intro` section from SOUL.md.
+ * Returns the first non-empty line under that heading, or null.
+ */
+function readSoulIdentityIntro(): string | null {
+  try {
+    const soulPath = getWorkspacePromptPath("SOUL.md");
+    if (!existsSync(soulPath)) return null;
+    const content = readFileSync(soulPath, "utf-8");
+
+    let inSection = false;
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (/^#+\s/.test(trimmed)) {
+        inSection = trimmed.toLowerCase().includes("identity intro");
+        continue;
+      }
+      if (inSection && trimmed.length > 0) {
+        return trimmed;
+      }
+    }
+  } catch {
+    // Fall through to cache/fallback
+  }
+  return null;
+}
+
+export function handleGetIdentityIntro(): Response {
+  // Prefer SOUL.md persisted intro over LLM-generated cache
+  const soulIntro = readSoulIdentityIntro();
+  if (soulIntro) {
+    return Response.json({ text: soulIntro });
+  }
+
+  const cached = getCachedIntro();
+  if (!cached) {
+    return httpError("NOT_FOUND", "No cached identity intro available", 404);
+  }
+  return Response.json({ text: cached.text });
+}
+
 // ---------------------------------------------------------------------------
 // Route definitions
 // ---------------------------------------------------------------------------
@@ -249,5 +295,10 @@ export function identityRouteDefinitions(): RouteDefinition[] {
       method: "GET",
       handler: () => handleGetIdentity(),
     },
+    {
+      endpoint: "identity/intro",
+      method: "GET",
+      handler: () => handleGetIdentityIntro(),
+    },
   ];
 }

package/src/runtime/routes/inbound-stages/escalation-intercept.ts

@@ -134,7 +134,7 @@ export function handleEscalationIntercept(
   void emitNotificationSignal({
     sourceEventName: "ingress.escalation",
     sourceChannel: sourceChannel as NotificationSourceChannel,
-    sourceSessionId: conversationId,
+    sourceContextId: conversationId,
     attentionHints: {
       requiresAction: true,
       urgency: "high",

package/src/runtime/routes/inbound-stages/verification-intercept.ts

@@ -231,7 +231,7 @@ export async function handleVerificationIntercept(
       void emitNotificationSignal({
         sourceEventName: "ingress.trusted_contact.activated",
         sourceChannel: sourceChannel as NotificationSourceChannel,
-        sourceSessionId: conversationId,
+        sourceContextId: conversationId,
         attentionHints: {
           requiresAction: false,
           urgency: "low",

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

@@ -11,12 +11,19 @@
  * results with is_valid flag and detailed error descriptions.
  */
 
+import { join } from "node:path";
 import { Database } from "bun:sqlite";
 
 import { invalidateConfigCache } from "../../config/loader.js";
 import { resetDb } from "../../memory/db-connection.js";
+import { clearCache as clearTrustCache } from "../../permissions/trust-store.js";
 import { getLogger } from "../../util/logger.js";
-import { getDbPath, getWorkspaceConfigPath } from "../../util/platform.js";
+import {
+  getDbPath,
+  getHooksDir,
+  getRootDir,
+  getWorkspaceDir,
+} from "../../util/platform.js";
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
 import { buildExportVBundle } from "../migrations/vbundle-builder.js";
@@ -135,13 +142,14 @@ export async function handleMigrationExport(req: Request): Promise<Response> {
 
   try {
     const { archive, manifest } = buildExportVBundle({
-      dbPath: getDbPath(),
-      configPath: getWorkspaceConfigPath(),
+      trustPath: join(getRootDir(), "protected", "trust.json"),
+      hooksDir: getHooksDir(),
+      workspaceDir: getWorkspaceDir(),
       source: "runtime-export",
       description,
       checkpoint: () => {
+        const dbPath = getDbPath();
         try {
-          const dbPath = getDbPath();
           const db = new Database(dbPath);
           try {
             db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
@@ -149,10 +157,10 @@ export async function handleMigrationExport(req: Request): Promise<Response> {
             db.close();
           }
         } catch (err) {
-          log.warn(
-            { err },
-            "WAL checkpoint failed — exporting without checkpoint",
-          );
+          // Best-effort: if the DB can't be checkpointed (e.g. not a valid
+          // SQLite file, missing WAL, etc.) we still proceed with the export
+          // using whatever is on disk.
+          log.warn({ err }, "WAL checkpoint failed — exporting without checkpoint");
         }
       },
     });
@@ -289,8 +297,9 @@ export async function handleMigrationImportPreflight(
 
     // Step 2: Analyze what would change on import
     const pathResolver = new DefaultPathResolver(
-      getDbPath(),
-      getWorkspaceConfigPath(),
+      join(getRootDir(), "protected"),
+      getWorkspaceDir(),
+      getHooksDir(),
     );
 
     const report = analyzeImport({
@@ -371,8 +380,9 @@ export async function handleMigrationImport(req: Request): Promise<Response> {
     }
 
     const pathResolver = new DefaultPathResolver(
-      getDbPath(),
-      getWorkspaceConfigPath(),
+      join(getRootDir(), "protected"),
+      getWorkspaceDir(),
+      getHooksDir(),
     );
 
     // Close the live SQLite connection before overwriting assistant.db on disk.
@@ -384,6 +394,7 @@ export async function handleMigrationImport(req: Request): Promise<Response> {
       pathResolver,
       preValidatedManifest: validation.manifest,
       preValidatedEntries: validation.entries,
+      workspaceDir: getWorkspaceDir(),
     });
 
     if (!result.ok) {
@@ -420,8 +431,9 @@ export async function handleMigrationImport(req: Request): Promise<Response> {
       );
     }
 
-    // Invalidate in-process config cache so imported settings.json takes effect
+    // Invalidate in-process caches so imported settings.json and trust.json take effect
     invalidateConfigCache();
+    clearTrustCache();
 
     return Response.json(result.report);
   } catch (err) {

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

@@ -11,6 +11,8 @@ import {
 } from "../../config/loader.js";
 import type { CesClient } from "../../credential-execution/client.js";
 import { setSentryOrganizationId } from "../../instrument.js";
+import { syncManualTokenConnection } from "../../oauth/manual-token-connection.js";
+import { validateAnthropicApiKey } from "../../providers/anthropic/client.js";
 import { initializeProviders } from "../../providers/registry.js";
 import { credentialKey } from "../../security/credential-key.js";
 import {
@@ -129,6 +131,21 @@ export async function handleAddSecret(
           400,
         );
       }
+      // Validate Anthropic API keys before storing
+      if (name === "anthropic") {
+        const validation = await validateAnthropicApiKey(value);
+        if (!validation.valid) {
+          log.warn(
+            { provider: name, reason: validation.reason },
+            "API key validation failed",
+          );
+          return Response.json(
+            { success: false, error: validation.reason },
+            { status: 422 },
+          );
+        }
+      }
+
       const stored = await setSecureKeyAsync(name, value);
       if (!stored) {
         return httpError(
@@ -201,6 +218,7 @@ export async function handleAddSecret(
           );
         }
         upsertCredentialMetadata(service, field, {});
+        await syncManualTokenConnection(service);
         if (service === "vellum" && field === "platform_base_url") {
           setPlatformBaseUrl(effectiveValue);
         }

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

@@ -43,8 +43,8 @@ import {
 } from "../../tools/execution-target.js";
 import { getAllTools, getTool } from "../../tools/registry.js";
 import {
-  injectReasonField,
-  REASON_SKIP_SET,
+  ACTIVITY_SKIP_SET,
+  injectActivityField,
 } from "../../tools/schema-transforms.js";
 import { isSideEffectTool } from "../../tools/side-effects.js";
 import { generateAndSaveAvatar } from "../../tools/system/avatar-generator.js";
@@ -400,17 +400,17 @@ function handleToolNamesList(): Response {
     }
   }
 
-  // Apply reason injection so settings/debug schemas match runtime behavior.
-  const transformedDefs = injectReasonField(rawDefs, REASON_SKIP_SET);
+  // Apply activity injection so settings/debug schemas match runtime behavior.
+  const transformedDefs = injectActivityField(rawDefs, ACTIVITY_SKIP_SET);
   for (const def of transformedDefs) {
     schemas[def.name] = def.input_schema as SchemaShape;
   }
 
   // Skill manifest schemas are served raw (untransformed). Unlike runtime tool
-  // schemas which have `reason` injected via injectReasonField(), skill manifests
-  // reflect the original TOOLS.json content. This is intentional: skill tools are
-  // invoked through skill_execute (which has its own reason field), so their
-  // individual schemas are never sent to the LLM directly.
+  // schemas which have `activity` injected via injectActivityField(), skill
+  // manifests reflect the original TOOLS.json content. This is intentional:
+  // skill tools are invoked through skill_execute (which has its own activity
+  // field), so their individual schemas are never sent to the LLM directly.
   try {
     const catalog = loadSkillCatalog();
     for (const skill of catalog) {
@@ -522,7 +522,7 @@ async function handleToolPermissionSimulate(body: {
     }
 
     return Response.json({
-      ok: true,
+      success: true,
       decision: result.decision,
       riskLevel,
       reason: result.reason,

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

@@ -0,0 +1,53 @@
+/**
+ * Route handlers for telemetry lifecycle events.
+ *
+ * POST /v1/telemetry/lifecycle — record a lifecycle event (app_open, hatch).
+ */
+
+import { recordLifecycleEvent } from "../../memory/lifecycle-events-store.js";
+import { getLogger } from "../../util/logger.js";
+import { httpError } from "../http-errors.js";
+import type { RouteDefinition } from "../http-router.js";
+
+const log = getLogger("telemetry-routes");
+
+const VALID_EVENT_NAMES = new Set(["app_open", "hatch"]);
+
+export async function handleRecordLifecycleEvent(
+  req: Request,
+): Promise<Response> {
+  let body: { event_name?: string };
+  try {
+    body = (await req.json()) as { event_name?: string };
+  } catch {
+    return httpError("BAD_REQUEST", "Invalid JSON body", 400);
+  }
+
+  const eventName = body.event_name;
+  if (!eventName || !VALID_EVENT_NAMES.has(eventName)) {
+    return httpError(
+      "BAD_REQUEST",
+      `event_name must be one of: ${[...VALID_EVENT_NAMES].join(", ")}`,
+      400,
+    );
+  }
+
+  const event = recordLifecycleEvent(eventName);
+  log.info({ eventName, eventId: event.id }, "Recorded lifecycle event");
+
+  return Response.json({ id: event.id, event_name: event.eventName });
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export function telemetryRouteDefinitions(): RouteDefinition[] {
+  return [
+    {
+      endpoint: "telemetry/lifecycle",
+      method: "POST",
+      handler: async ({ req }) => handleRecordLifecycleEvent(req),
+    },
+  ];
+}

package/src/runtime/routes/trace-event-routes.ts

@@ -0,0 +1,62 @@
+/**
+ * HTTP route handlers for trace event retrieval.
+ *
+ * GET /v1/trace-events — Returns persisted trace events for a conversation.
+ */
+
+import { getTraceEvents } from "../../memory/trace-event-store.js";
+import { httpError } from "../http-errors.js";
+import type { RouteDefinition } from "../http-router.js";
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export function traceEventRouteDefinitions(): RouteDefinition[] {
+  return [
+    {
+      endpoint: "trace-events",
+      method: "GET",
+      handler: ({ url }) => {
+        const conversationId = url.searchParams.get("conversationId");
+        if (!conversationId) {
+          return httpError(
+            "BAD_REQUEST",
+            "conversationId query parameter is required",
+            400,
+          );
+        }
+
+        const limitParam = url.searchParams.get("limit");
+        const afterSequenceParam = url.searchParams.get("afterSequence");
+
+        const limit = limitParam ? parseInt(limitParam, 10) : undefined;
+        if (limitParam && (isNaN(limit!) || limit! <= 0)) {
+          return httpError(
+            "BAD_REQUEST",
+            "limit must be a positive integer",
+            400,
+          );
+        }
+
+        const afterSequence = afterSequenceParam
+          ? parseInt(afterSequenceParam, 10)
+          : undefined;
+        if (afterSequenceParam && (isNaN(afterSequence!) || afterSequence! < 0)) {
+          return httpError(
+            "BAD_REQUEST",
+            "afterSequence must be a non-negative integer",
+            400,
+          );
+        }
+
+        const events = getTraceEvents(conversationId, {
+          limit,
+          afterSequence,
+        });
+
+        return Response.json({ events });
+      },
+    },
+  ];
+}

package/src/runtime/tool-grant-request-helper.ts

@@ -146,7 +146,7 @@ export function createOrReuseToolGrantRequest(
   const signalPromise = emitNotificationSignal({
     sourceEventName: "guardian.question",
     sourceChannel: sourceChannel as NotificationSourceChannel,
-    sourceSessionId: conversationId,
+    sourceContextId: conversationId,
     attentionHints: {
       requiresAction: true,
       urgency: "high",

package/src/runtime/verification-outbound-actions.ts

@@ -116,6 +116,12 @@ export interface OutboundActionResult {
   pendingBootstrap?: boolean;
   /** Echoed back so consumers know which conversation to target for pointers. */
   originConversationId?: string;
+  /** Internal: Slack DM delivery payload for the caller to dispatch.
+   *  The shared startOutbound/resendOutbound functions no longer fire the
+   *  delivery themselves because CLI subprocesses are sandboxed and cannot
+   *  reach the gateway.  The daemon HTTP route handler calls
+   *  deliverVerificationSlack() after receiving this payload. */
+  _pendingSlackDm?: { userId: string; text: string; assistantId: string };
 }
 
 // ---------------------------------------------------------------------------
@@ -486,42 +492,52 @@ function startOutboundVoice(
 
 /**
  * Deliver a verification Slack DM via the gateway's /deliver/slack endpoint.
- * Fire-and-forget with error logging.
+ * Returns a promise that resolves when the delivery attempt completes.
  */
-export function deliverVerificationSlack(
+export async function deliverVerificationSlackAsync(
   userId: string,
   text: string,
   assistantId: string,
-): void {
-  (async () => {
-    try {
-      const gatewayUrl = getGatewayInternalBaseUrl();
-      const bearerToken = mintDaemonDeliveryToken();
-      const url = `${gatewayUrl}/deliver/slack`;
-      const resp = await fetch(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${bearerToken}`,
-        },
-        body: JSON.stringify({ chatId: userId, text, assistantId }),
-      });
-      if (!resp.ok) {
-        const body = await resp.text().catch(() => "<unreadable>");
-        log.error(
-          { userId, assistantId, status: resp.status, body },
-          "Gateway /deliver/slack failed for verification",
-        );
-      } else {
-        log.info({ userId, assistantId }, "Verification Slack DM delivered");
-      }
-    } catch (err) {
+): Promise<void> {
+  try {
+    const gatewayUrl = getGatewayInternalBaseUrl();
+    const bearerToken = mintDaemonDeliveryToken();
+    const url = `${gatewayUrl}/deliver/slack`;
+    const resp = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${bearerToken}`,
+      },
+      body: JSON.stringify({ chatId: userId, text, assistantId }),
+    });
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => "<unreadable>");
       log.error(
-        { err, userId, assistantId },
-        "Failed to deliver verification Slack DM",
+        { userId, assistantId, status: resp.status, body },
+        "Gateway /deliver/slack failed for verification",
       );
+    } else {
+      log.info({ userId, assistantId }, "Verification Slack DM delivered");
     }
-  })();
+  } catch (err) {
+    log.error(
+      { err, userId, assistantId },
+      "Failed to deliver verification Slack DM",
+    );
+  }
+}
+
+/**
+ * Deliver a verification Slack DM via the gateway's /deliver/slack endpoint.
+ * Fire-and-forget wrapper for use in the daemon process (HTTP route handlers).
+ */
+export function deliverVerificationSlack(
+  userId: string,
+  text: string,
+  assistantId: string,
+): void {
+  deliverVerificationSlackAsync(userId, text, assistantId);
 }
 
 function startOutboundSlack(
@@ -588,7 +604,6 @@ function startOutboundSlack(
   const sendCount = 1;
 
   updateSessionDelivery(sessionResult.sessionId, now, sendCount, nextResendAt);
-  deliverVerificationSlack(destination, slackBody, assistantId);
 
   return {
     success: true,
@@ -599,6 +614,7 @@ function startOutboundSlack(
     sendCount,
     channel,
     originConversationId,
+    _pendingSlackDm: { userId: destination, text: slackBody, assistantId },
   };
 }
 
@@ -788,7 +804,6 @@ export function resendOutbound(
       newSendCount,
       nextResendAt,
     );
-    deliverVerificationSlack(destination, slackBody, assistantId);
 
     return {
       success: true,
@@ -798,6 +813,7 @@ export function resendOutbound(
       sendCount: newSendCount,
       channel,
       originConversationId,
+      _pendingSlackDm: { userId: destination, text: slackBody, assistantId },
     };
   }