@vellumai/assistant 0.4.54 → 0.4.56

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

@@ -1,8 +1,16 @@
+import {
+  setPlatformAssistantId,
+  setPlatformBaseUrl,
+  setPlatformOrganizationId,
+  setPlatformUserId,
+} from "../../config/env.js";
 import {
   API_KEY_PROVIDERS,
   getConfig,
   invalidateConfigCache,
 } from "../../config/loader.js";
+import type { CesClient } from "../../credential-execution/client.js";
+import { setSentryOrganizationId } from "../../instrument.js";
 import { initializeProviders } from "../../providers/registry.js";
 import { credentialKey } from "../../security/credential-key.js";
 import {
@@ -20,19 +28,76 @@ import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
 
 const log = getLogger("runtime-http");
-const MANAGED_PROXY_CREDENTIAL = {
-  service: "vellum",
-  field: "assistant_api_key",
-};
+const MANAGED_PROXY_CREDENTIALS = [
+  { service: "vellum", field: "assistant_api_key" },
+  { service: "vellum", field: "platform_base_url" },
+] as const;
 
 function isManagedProxyCredential(service: string, field: string): boolean {
-  return (
-    service === MANAGED_PROXY_CREDENTIAL.service &&
-    field === MANAGED_PROXY_CREDENTIAL.field
+  return MANAGED_PROXY_CREDENTIALS.some(
+    (c) => c.service === service && c.field === field,
+  );
+}
+
+const CES_READY_POLL_INTERVAL_MS = 500;
+const CES_READY_POLL_TIMEOUT_MS = 30_000;
+
+/** Monotonic counter that increments each time a new assistant API key is handled.
+ *  Queued propagation attempts check this before pushing to avoid overwriting
+ *  a newer key with a stale one. */
+let apiKeyGeneration = 0;
+
+/**
+ * Poll the CES client until it becomes ready, then push the API key —
+ * but only if no newer key has been handled in the meantime.
+ */
+async function queueApiKeyPropagation(
+  cesClient: CesClient,
+  apiKey: string,
+  generation: number,
+): Promise<void> {
+  log.info(
+    "CES client not ready — queuing API key propagation until handshake completes",
+  );
+  const deadline = Date.now() + CES_READY_POLL_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, CES_READY_POLL_INTERVAL_MS));
+    if (generation < apiKeyGeneration) {
+      log.info(
+        "Discarding stale queued API key propagation — a newer key was already handled",
+      );
+      return;
+    }
+    if (cesClient.isReady()) {
+      if (generation < apiKeyGeneration) {
+        log.info(
+          "Discarding stale queued API key propagation — a newer key was already handled",
+        );
+        return;
+      }
+      try {
+        await cesClient.updateAssistantApiKey(apiKey);
+        log.info(
+          "Pushed queued assistant API key to CES after handshake completed",
+        );
+      } catch (err) {
+        log.warn(
+          { error: err instanceof Error ? err.message : String(err) },
+          "Failed to push queued assistant API key to CES (non-fatal)",
+        );
+      }
+      return;
+    }
+  }
+  log.warn(
+    "Timed out waiting for CES client to become ready — API key was not propagated",
   );
 }
 
-export async function handleAddSecret(req: Request): Promise<Response> {
+export async function handleAddSecret(
+  req: Request,
+  getCesClient?: () => CesClient | undefined,
+): Promise<Response> {
   const body = (await req.json()) as {
     type?: string;
     name?: string;
@@ -91,17 +156,92 @@ export async function handleAddSecret(req: Request): Promise<Response> {
       const service = name.slice(0, colonIdx);
       const field = name.slice(colonIdx + 1);
       const key = credentialKey(service, field);
-      const stored = await setSecureKeyAsync(key, value);
-      if (!stored) {
-        return httpError(
-          "INTERNAL_ERROR",
-          "Failed to store credential in secure storage",
-          500,
-        );
+
+      // For identity fields, trim whitespace before persisting so the
+      // credential store matches the in-memory value.  Whitespace-only
+      // input is treated as a no-op: nothing is stored and in-memory
+      // state is cleared.
+      const TRIMMED_IDENTITY_FIELDS = new Set([
+        "platform_assistant_id",
+        "platform_organization_id",
+        "platform_user_id",
+      ]);
+      const isTrimmedIdentity =
+        service === "vellum" && TRIMMED_IDENTITY_FIELDS.has(field);
+      const effectiveValue = isTrimmedIdentity ? value.trim() : value;
+
+      if (isTrimmedIdentity && effectiveValue === "") {
+        // Whitespace-only → remove stale credential from the secure store,
+        // then clear in-memory state. Delete first so that if it fails we
+        // return 500 without having mutated in-memory identity.
+        const deleteResult = await deleteSecureKeyAsync(key);
+        if (deleteResult === "error") {
+          return httpError(
+            "INTERNAL_ERROR",
+            `Failed to delete stale credential from secure storage: ${service}:${field}`,
+            500,
+          );
+        }
+        if (field === "platform_assistant_id") {
+          setPlatformAssistantId(undefined);
+        } else if (field === "platform_organization_id") {
+          setPlatformOrganizationId(undefined);
+          setSentryOrganizationId(undefined);
+        } else if (field === "platform_user_id") {
+          setPlatformUserId(undefined);
+        }
+        deleteCredentialMetadata(service, field);
+      } else {
+        const stored = await setSecureKeyAsync(key, effectiveValue);
+        if (!stored) {
+          return httpError(
+            "INTERNAL_ERROR",
+            "Failed to store credential in secure storage",
+            500,
+          );
+        }
+        upsertCredentialMetadata(service, field, {});
+        if (service === "vellum" && field === "platform_base_url") {
+          setPlatformBaseUrl(effectiveValue);
+        }
+        if (service === "vellum" && field === "platform_assistant_id") {
+          setPlatformAssistantId(effectiveValue || undefined);
+        }
+        if (service === "vellum" && field === "platform_organization_id") {
+          setPlatformOrganizationId(effectiveValue || undefined);
+          setSentryOrganizationId(effectiveValue || undefined);
+        }
+        if (service === "vellum" && field === "platform_user_id") {
+          setPlatformUserId(effectiveValue || undefined);
+        }
       }
-      upsertCredentialMetadata(service, field, {});
       if (isManagedProxyCredential(service, field)) {
         await initializeProviders(getConfig());
+        if (service === "vellum" && field === "assistant_api_key") {
+          // Push the API key to CES so managed credential materialization
+          // works even though the handshake ran before the key was available.
+          const generation = ++apiKeyGeneration;
+          const cesClient = getCesClient?.();
+          if (cesClient) {
+            if (cesClient.isReady()) {
+              try {
+                await cesClient.updateAssistantApiKey(value);
+                log.info(
+                  "Pushed assistant API key to CES after managed proxy credential update",
+                );
+              } catch (err) {
+                log.warn(
+                  { error: err instanceof Error ? err.message : String(err) },
+                  "Failed to push assistant API key to CES (non-fatal)",
+                );
+              }
+            } else {
+              // CES handshake is still in flight — queue the key propagation
+              // so it fires once CES becomes ready.
+              void queueApiKeyPropagation(cesClient, value, generation);
+            }
+          }
+        }
       }
       log.info({ service, field }, "Credential added via HTTP");
       return Response.json({ success: true, type, name }, { status: 201 });
@@ -195,6 +335,19 @@ export async function handleDeleteSecret(req: Request): Promise<Response> {
         );
       }
       deleteCredentialMetadata(service, field);
+      if (service === "vellum" && field === "platform_base_url") {
+        setPlatformBaseUrl(undefined);
+      }
+      if (service === "vellum" && field === "platform_assistant_id") {
+        setPlatformAssistantId(undefined);
+      }
+      if (service === "vellum" && field === "platform_organization_id") {
+        setPlatformOrganizationId(undefined);
+        setSentryOrganizationId(undefined);
+      }
+      if (service === "vellum" && field === "platform_user_id") {
+        setPlatformUserId(undefined);
+      }
       if (isManagedProxyCredential(service, field)) {
         await initializeProviders(getConfig());
       }
@@ -218,12 +371,19 @@ export async function handleDeleteSecret(req: Request): Promise<Response> {
 // Route definitions
 // ---------------------------------------------------------------------------
 
-export function secretRouteDefinitions(): RouteDefinition[] {
+export interface SecretRouteDeps {
+  /** Accessor for the CES client, used to push API key updates after hatch. */
+  getCesClient?: () => CesClient | undefined;
+}
+
+export function secretRouteDefinitions(
+  deps?: SecretRouteDeps,
+): RouteDefinition[] {
   return [
     {
       endpoint: "secrets",
       method: "POST",
-      handler: async ({ req }) => handleAddSecret(req),
+      handler: async ({ req }) => handleAddSecret(req, deps?.getCesClient),
     },
     {
       endpoint: "secrets",

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

@@ -47,7 +47,7 @@ import {
   REASON_SKIP_SET,
 } from "../../tools/schema-transforms.js";
 import { isSideEffectTool } from "../../tools/side-effects.js";
-import { setAvatarTool } from "../../tools/system/avatar-generator.js";
+import { generateAndSaveAvatar } from "../../tools/system/avatar-generator.js";
 import { pathExists } from "../../util/fs.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspaceDir } from "../../util/platform.js";
@@ -78,6 +78,7 @@ function handleVoiceConfigUpdate(activationKey: string): Response {
 // Avatar generation
 // ---------------------------------------------------------------------------
 
+// Also callable via the `vellum-avatar` skill's AI generation mode.
 async function handleGenerateAvatar(description: string): Promise<Response> {
   if (!description.trim()) {
     return httpError("BAD_REQUEST", "Description is required.", 400);
@@ -86,11 +87,7 @@ async function handleGenerateAvatar(description: string): Promise<Response> {
   log.info({ description }, "Generating avatar via HTTP request");
 
   try {
-    const result = await setAvatarTool.execute(
-      { description },
-      // Minimal tool context -- avatar generation needs no session context
-      {} as Parameters<typeof setAvatarTool.execute>[1],
-    );
+    const result = await generateAndSaveAvatar(description);
 
     if (result.isError) {
       return httpError("INTERNAL_ERROR", result.content, 500);
@@ -100,8 +97,22 @@ async function handleGenerateAvatar(description: string): Promise<Response> {
       getWorkspaceDir(),
       "data",
       "avatar",
-      "custom-avatar.png",
+      "avatar-image.png",
     );
+
+    // Notify all connected SSE clients so every macOS/iOS instance
+    // reloads the avatar image immediately.
+    assistantEventHub
+      .publish(
+        buildAssistantEvent(DAEMON_INTERNAL_ASSISTANT_ID, {
+          type: "avatar_updated",
+          avatarPath,
+        }),
+      )
+      .catch((err) => {
+        log.warn({ err }, "Failed to publish avatar_updated event");
+      });
+
     return Response.json({ ok: true, avatarPath });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -176,7 +187,9 @@ async function handleOAuthConnectStart(body: {
     if (dbApp) {
       clientId = dbApp.clientId;
       if (!clientSecret) {
-        clientSecret = await getSecureKeyAsync(dbApp.clientSecretCredentialPath);
+        clientSecret = await getSecureKeyAsync(
+          dbApp.clientSecretCredentialPath,
+        );
       }
     }
   }
@@ -466,7 +479,7 @@ async function handleToolPermissionSimulate(body: {
       manifestOverride,
     );
 
-    // Private-thread override
+    // Private-conversation override
     if (
       body.forcePromptSideEffects &&
       result.decision === "allow" &&
@@ -474,7 +487,7 @@ async function handleToolPermissionSimulate(body: {
     ) {
       result.decision = "prompt";
       result.reason =
-        "Private thread: side-effect tools require explicit approval";
+        "Private conversation: side-effect tools require explicit approval";
     }
 
     // Non-interactive override

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

@@ -16,6 +16,8 @@ import {
   disableSkill,
   draftSkill,
   enableSkill,
+  getSkill,
+  getSkillFiles,
   inspectSkill,
   installSkill,
   listSkills,
@@ -49,6 +51,23 @@ export function skillRouteDefinitions(deps: SkillRouteDeps): RouteDefinition[] {
       },
     },
 
+    // GET /v1/skills/:id/files — skill metadata + directory contents
+    {
+      endpoint: "skills/:id/files",
+      method: "GET",
+      policyKey: "skills",
+      handler: ({ params }) => {
+        const result = getSkillFiles(params.id, ctx());
+        if ("error" in result) {
+          if (result.status === 404) {
+            return httpError("NOT_FOUND", result.error, 404);
+          }
+          return httpError("INTERNAL_ERROR", result.error, 500);
+        }
+        return Response.json(result);
+      },
+    },
+
     // POST /v1/skills/:id/enable — enable skill
     {
       endpoint: "skills/:id/enable",
@@ -250,6 +269,25 @@ export function skillRouteDefinitions(deps: SkillRouteDeps): RouteDefinition[] {
       },
     },
 
+    // GET /v1/skills/:id — single skill metadata
+    // Registered after all literal-segment GET routes (search, inspect, files)
+    // to avoid shadowing them with the parametric :id match.
+    {
+      endpoint: "skills/:id",
+      method: "GET",
+      policyKey: "skills",
+      handler: ({ params }) => {
+        const result = getSkill(params.id, ctx());
+        if ("error" in result) {
+          if (result.status === 404) {
+            return httpError("NOT_FOUND", result.error, 404);
+          }
+          return httpError("INTERNAL_ERROR", result.error, 500);
+        }
+        return Response.json(result);
+      },
+    },
+
     // DELETE /v1/skills/:id — uninstall skill
     {
       endpoint: "skills/:id",

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

@@ -158,17 +158,17 @@ export function subagentRouteDefinitions(): RouteDefinition[] {
       method: "POST",
       policyKey: "subagents/abort",
       handler: async ({ req, params }) => {
-        const body = (await req.json()) as { sessionId?: string };
-        const sessionId = body.sessionId;
-        if (!sessionId || typeof sessionId !== "string") {
-          return httpError("BAD_REQUEST", "sessionId is required", 400);
+        const body = (await req.json()) as { conversationId?: string };
+        const conversationId = body.conversationId;
+        if (!conversationId || typeof conversationId !== "string") {
+          return httpError("BAD_REQUEST", "conversationId is required", 400);
         }
 
         const manager = getSubagentManager();
         const aborted = manager.abort(
           params.id,
           () => {}, // No send callback needed for HTTP
-          sessionId,
+          conversationId,
         );
 
         if (!aborted) {
@@ -194,12 +194,12 @@ export function subagentRouteDefinitions(): RouteDefinition[] {
       policyKey: "subagents/message",
       handler: async ({ req, params }) => {
         const body = (await req.json()) as {
-          sessionId?: string;
+          conversationId?: string;
           content?: string;
         };
-        const sessionId = body.sessionId;
-        if (!sessionId || typeof sessionId !== "string") {
-          return httpError("BAD_REQUEST", "sessionId is required", 400);
+        const conversationId = body.conversationId;
+        if (!conversationId || typeof conversationId !== "string") {
+          return httpError("BAD_REQUEST", "conversationId is required", 400);
         }
         if (!body.content || typeof body.content !== "string") {
           return httpError("BAD_REQUEST", "content is required", 400);
@@ -209,7 +209,7 @@ export function subagentRouteDefinitions(): RouteDefinition[] {
 
         // Ownership check
         const state = manager.getState(params.id);
-        if (!state || state.config.parentSessionId !== sessionId) {
+        if (!state || state.config.parentConversationId !== conversationId) {
           return httpError(
             "NOT_FOUND",
             `Subagent "${params.id}" not found or in terminal state.`,

package/src/runtime/routes/surface-action-routes.ts

@@ -1,8 +1,8 @@
 /**
  * Route handler for surface action operations.
  *
- * POST /v1/surface-actions — dispatch a surface action to an active session.
- * Requires the session to already exist (does not create new sessions).
+ * POST /v1/surface-actions — dispatch a surface action to an active conversation.
+ * Requires the conversation to already exist (does not create new conversations).
  */
 import { getLogger } from "../../util/logger.js";
 import { httpError } from "../http-errors.js";
@@ -20,32 +20,32 @@ interface SurfaceActionTarget {
   handleSurfaceUndo?(surfaceId: string): void;
 }
 
-export type SessionLookup = (
-  sessionId: string,
+export type ConversationLookup = (
+  conversationId: string,
 ) => SurfaceActionTarget | undefined;
 
-export type SessionLookupBySurfaceId = (
+export type ConversationLookupBySurfaceId = (
   surfaceId: string,
 ) => SurfaceActionTarget | undefined;
 
 /**
  * POST /v1/surface-actions — handle a UI surface action.
  *
- * Body: { sessionId?, surfaceId, actionId, data? }
+ * Body: { conversationId?, surfaceId, actionId, data? }
  */
 export async function handleSurfaceAction(
   req: Request,
-  findSession: SessionLookup,
-  findSessionBySurfaceId?: SessionLookupBySurfaceId,
+  findConversation: ConversationLookup,
+  findConversationBySurfaceId?: ConversationLookupBySurfaceId,
 ): Promise<Response> {
   const body = (await req.json()) as {
-    sessionId?: string | null;
+    conversationId?: string | null;
     surfaceId?: string;
     actionId?: string;
     data?: Record<string, unknown>;
   };
 
-  const { sessionId, surfaceId, actionId, data } = body;
+  const { conversationId, surfaceId, actionId, data } = body;
 
   if (!surfaceId || typeof surfaceId !== "string") {
     return httpError("BAD_REQUEST", "surfaceId is required", 400);
@@ -53,28 +53,28 @@ export async function handleSurfaceAction(
   if (!actionId || typeof actionId !== "string") {
     return httpError("BAD_REQUEST", "actionId is required", 400);
   }
-  if (sessionId != null && typeof sessionId !== "string") {
-    return httpError("BAD_REQUEST", "sessionId must be a string", 400);
+  if (conversationId != null && typeof conversationId !== "string") {
+    return httpError("BAD_REQUEST", "conversationId must be a string", 400);
   }
 
-  const session = sessionId
-    ? findSession(sessionId)
-    : findSessionBySurfaceId?.(surfaceId);
+  const conversation = conversationId
+    ? findConversation(conversationId)
+    : findConversationBySurfaceId?.(surfaceId);
 
-  if (!session) {
-    return httpError("NOT_FOUND", "No active session found", 404);
+  if (!conversation) {
+    return httpError("NOT_FOUND", "No active conversation found", 404);
   }
 
   try {
-    session.handleSurfaceAction(surfaceId, actionId, data);
+    conversation.handleSurfaceAction(surfaceId, actionId, data);
     log.info(
-      { sessionId: sessionId ?? undefined, surfaceId, actionId },
+      { conversationId: conversationId ?? undefined, surfaceId, actionId },
       "Surface action handled via HTTP",
     );
     return Response.json({ ok: true });
   } catch (err) {
     log.error(
-      { err, sessionId: sessionId ?? undefined, surfaceId, actionId },
+      { err, conversationId: conversationId ?? undefined, surfaceId, actionId },
       "Failed to handle surface action via HTTP",
     );
     return httpError("INTERNAL_ERROR", "Failed to handle surface action", 500);
@@ -88,47 +88,47 @@ export async function handleSurfaceAction(
 /**
  * POST /v1/surfaces/:id/undo — undo the last surface action.
  *
- * Body: { sessionId }
+ * Body: { conversationId }
  */
 export async function handleSurfaceUndo(
   req: Request,
   surfaceId: string,
-  findSession: SessionLookup,
-  findSessionBySurfaceId?: SessionLookupBySurfaceId,
+  findConversation: ConversationLookup,
+  findConversationBySurfaceId?: ConversationLookupBySurfaceId,
 ): Promise<Response> {
   const body = (await req.json()) as {
-    sessionId?: string | null;
+    conversationId?: string | null;
   };
 
-  const { sessionId } = body;
+  const { conversationId } = body;
 
-  if (sessionId != null && typeof sessionId !== "string") {
-    return httpError("BAD_REQUEST", "sessionId must be a string", 400);
+  if (conversationId != null && typeof conversationId !== "string") {
+    return httpError("BAD_REQUEST", "conversationId must be a string", 400);
   }
 
-  const session = sessionId
-    ? findSession(sessionId)
-    : findSessionBySurfaceId?.(surfaceId);
+  const conversation = conversationId
+    ? findConversation(conversationId)
+    : findConversationBySurfaceId?.(surfaceId);
 
-  if (!session) {
-    return httpError("NOT_FOUND", "No active session found", 404);
+  if (!conversation) {
+    return httpError("NOT_FOUND", "No active conversation found", 404);
   }
 
-  if (!session.handleSurfaceUndo) {
+  if (!conversation.handleSurfaceUndo) {
     return httpError(
       "NOT_IMPLEMENTED",
-      "Surface undo not supported for this session type",
+      "Surface undo not supported for this conversation type",
       501,
     );
   }
 
   try {
-    session.handleSurfaceUndo(surfaceId);
-    log.info({ sessionId, surfaceId }, "Surface undo handled via HTTP");
+    conversation.handleSurfaceUndo(surfaceId);
+    log.info({ conversationId, surfaceId }, "Surface undo handled via HTTP");
     return Response.json({ ok: true });
   } catch (err) {
     log.error(
-      { err, sessionId, surfaceId },
+      { err, conversationId, surfaceId },
       "Failed to handle surface undo via HTTP",
     );
     return httpError("INTERNAL_ERROR", "Failed to handle surface undo", 500);
@@ -136,15 +136,15 @@ export async function handleSurfaceUndo(
 }
 
 export function surfaceActionRouteDefinitions(deps: {
-  findSession?: SessionLookup;
-  findSessionBySurfaceId?: SessionLookupBySurfaceId;
+  findConversation?: ConversationLookup;
+  findConversationBySurfaceId?: ConversationLookupBySurfaceId;
 }): RouteDefinition[] {
   return [
     {
       endpoint: "surface-actions",
       method: "POST",
       handler: async ({ req }) => {
-        if (!deps.findSession) {
+        if (!deps.findConversation) {
           return httpError(
             "NOT_IMPLEMENTED",
             "Surface actions not available",
@@ -153,8 +153,8 @@ export function surfaceActionRouteDefinitions(deps: {
         }
         return handleSurfaceAction(
           req,
-          deps.findSession,
-          deps.findSessionBySurfaceId,
+          deps.findConversation,
+          deps.findConversationBySurfaceId,
         );
       },
     },
@@ -162,7 +162,7 @@ export function surfaceActionRouteDefinitions(deps: {
       endpoint: "surfaces/:id/undo",
       method: "POST",
       handler: async ({ req, params }) => {
-        if (!deps.findSession) {
+        if (!deps.findConversation) {
           return httpError(
             "NOT_IMPLEMENTED",
             "Surface undo not available",
@@ -172,8 +172,8 @@ export function surfaceActionRouteDefinitions(deps: {
         return handleSurfaceUndo(
           req,
           params.id,
-          deps.findSession,
-          deps.findSessionBySurfaceId,
+          deps.findConversation,
+          deps.findConversationBySurfaceId,
         );
       },
     },