@vellumai/assistant 0.4.55 → 0.4.57

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

@@ -1,8 +1,18 @@
+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 { 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 {
@@ -20,19 +30,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;
@@ -64,6 +131,21 @@ export async function handleAddSecret(req: Request): Promise<Response> {
           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(
@@ -91,17 +173,93 @@ 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, {});
+        await syncManualTokenConnection(service);
+        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 +353,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 +389,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

@@ -43,11 +43,11 @@ 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 { 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,
+        );
       }
     }
   }
@@ -387,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) {
@@ -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.`,