@vellumai/credential-executor 0.5.12 → 0.5.13

package/node_modules/@vellumai/ces-contracts/src/index.ts

@@ -33,6 +33,13 @@ export const HandshakeRequestSchema = z.object({
    * can use it for platform credential materialisation.
    */
   assistantApiKey: z.string().optional(),
+  /**
+   * Optional platform assistant ID passed from the assistant runtime.
+   * In managed (sidecar) mode with warm pools, the PLATFORM_ASSISTANT_ID
+   * env var may not be set at CES startup. The assistant forwards it here
+   * so CES can use it for platform credential materialisation.
+   */
+  assistantId: z.string().optional(),
 });
 export type HandshakeRequest = z.infer<typeof HandshakeRequestSchema>;
 

package/node_modules/@vellumai/ces-contracts/src/rpc.ts

@@ -422,6 +422,11 @@ export type ListAuditRecordsResponse = z.infer<
 export const UpdateManagedCredentialSchema = z.object({
   /** The assistant API key to push to CES for platform credential materialization. */
   assistantApiKey: z.string(), // nosemgrep: not-a-secret
+  /**
+   * Optional platform assistant ID. In warm-pool mode the ID may not be
+   * available at CES startup; the assistant pushes it here once provisioned.
+   */
+  assistantId: z.string().optional(),
 });
 export type UpdateManagedCredential = z.infer<
   typeof UpdateManagedCredentialSchema

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/credential-executor",
-  "version": "0.5.12",
+  "version": "0.5.13",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/managed-lazy-getters.test.ts

@@ -11,6 +11,7 @@ import { describe, expect, test } from "bun:test";
 import {
   buildLazyGetters,
   type ApiKeyRef,
+  type AssistantIdRef,
 } from "../managed-lazy-getters.js";
 
 // ---------------------------------------------------------------------------
@@ -20,9 +21,10 @@ import {
 describe("managed lazy getters — before API key arrives", () => {
   test("apiKeyRef starts empty and managed subject options are undefined", () => {
     const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
     const { getManagedSubjectOptions } = buildLazyGetters({
       platformBaseUrl: "https://api.vellum.ai",
-      assistantId: "ast_abc123",
+      assistantIdRef,
       apiKeyRef,
     });
 
@@ -32,9 +34,10 @@ describe("managed lazy getters — before API key arrives", () => {
 
   test("apiKeyRef starts empty and managed materializer options are undefined", () => {
     const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
     const { getManagedMaterializerOptions } = buildLazyGetters({
       platformBaseUrl: "https://api.vellum.ai",
-      assistantId: "ast_abc123",
+      assistantIdRef,
       apiKeyRef,
     });
 
@@ -43,9 +46,10 @@ describe("managed lazy getters — before API key arrives", () => {
 
   test("getAssistantApiKey returns empty string when ref is empty and no env var", () => {
     const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
     const { getAssistantApiKey } = buildLazyGetters({
       platformBaseUrl: "https://api.vellum.ai",
-      assistantId: "ast_abc123",
+      assistantIdRef,
       apiKeyRef,
     });
 
@@ -60,9 +64,10 @@ describe("managed lazy getters — before API key arrives", () => {
 describe("managed lazy getters — after API key arrives via handshake", () => {
   test("setting apiKeyRef.current enables managed subject options", () => {
     const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
     const { getManagedSubjectOptions } = buildLazyGetters({
       platformBaseUrl: "https://api.vellum.ai",
-      assistantId: "ast_abc123",
+      assistantIdRef,
       apiKeyRef,
     });
 
@@ -79,9 +84,10 @@ describe("managed lazy getters — after API key arrives via handshake", () => {
 
   test("setting apiKeyRef.current enables managed materializer options", () => {
     const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
     const { getManagedMaterializerOptions } = buildLazyGetters({
       platformBaseUrl: "https://api.vellum.ai",
-      assistantId: "ast_abc123",
+      assistantIdRef,
       apiKeyRef,
     });
 
@@ -98,10 +104,11 @@ describe("managed lazy getters — after API key arrives via handshake", () => {
 
   test("returned options contain the exact key from the ref (not a stale copy)", () => {
     const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
     const { getManagedSubjectOptions, getManagedMaterializerOptions } =
       buildLazyGetters({
         platformBaseUrl: "https://api.vellum.ai",
-        assistantId: "ast_abc123",
+        assistantIdRef,
         apiKeyRef,
       });
 
@@ -122,11 +129,12 @@ describe("managed lazy getters — after API key arrives via handshake", () => {
 describe("managed lazy getters — lazy resolution timing", () => {
   test("handlers built before key arrives resolve the key at call time", () => {
     const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
 
     const { getManagedSubjectOptions, getManagedMaterializerOptions } =
       buildLazyGetters({
         platformBaseUrl: "https://api.vellum.ai",
-        assistantId: "ast_abc123",
+        assistantIdRef,
         apiKeyRef,
       });
 
@@ -147,10 +155,11 @@ describe("managed lazy getters — lazy resolution timing", () => {
 
   test("deps object with getter properties resolves lazily (mirrors httpDeps pattern)", () => {
     const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
     const { getManagedSubjectOptions, getManagedMaterializerOptions } =
       buildLazyGetters({
         platformBaseUrl: "https://api.vellum.ai",
-        assistantId: "ast_abc123",
+        assistantIdRef,
         apiKeyRef,
       });
 
@@ -182,9 +191,10 @@ describe("managed lazy getters — lazy resolution timing", () => {
 
   test("env var fallback is used when ref is empty", () => {
     const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
     const { getAssistantApiKey, getManagedSubjectOptions } = buildLazyGetters({
       platformBaseUrl: "https://api.vellum.ai",
-      assistantId: "ast_abc123",
+      assistantIdRef,
       apiKeyRef,
       envApiKey: "vak_env_fallback",
     });
@@ -198,9 +208,10 @@ describe("managed lazy getters — lazy resolution timing", () => {
 
   test("handshake-provided key takes precedence over env var", () => {
     const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
     const { getAssistantApiKey } = buildLazyGetters({
       platformBaseUrl: "https://api.vellum.ai",
-      assistantId: "ast_abc123",
+      assistantIdRef,
       apiKeyRef,
       envApiKey: "vak_env_key",
     });
@@ -219,10 +230,11 @@ describe("managed lazy getters — lazy resolution timing", () => {
 describe("managed lazy getters — missing platform config fields", () => {
   test("missing platformBaseUrl returns undefined even with API key", () => {
     const apiKeyRef: ApiKeyRef = { current: "vak_test_key" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
     const { getManagedSubjectOptions, getManagedMaterializerOptions } =
       buildLazyGetters({
         platformBaseUrl: "",
-        assistantId: "ast_abc123",
+        assistantIdRef,
         apiKeyRef,
       });
 
@@ -232,14 +244,51 @@ describe("managed lazy getters — missing platform config fields", () => {
 
   test("missing assistantId returns undefined even with API key", () => {
     const apiKeyRef: ApiKeyRef = { current: "vak_test_key" };
+    const assistantIdRef: AssistantIdRef = { current: "" };
     const { getManagedSubjectOptions, getManagedMaterializerOptions } =
       buildLazyGetters({
         platformBaseUrl: "https://api.vellum.ai",
-        assistantId: "",
+        assistantIdRef,
         apiKeyRef,
       });
 
     expect(getManagedSubjectOptions()).toBeUndefined();
     expect(getManagedMaterializerOptions()).toBeUndefined();
   });
+
+  test("assistantIdRef updated after build enables options (warm-pool scenario)", () => {
+    /**
+     * Verifies that updating assistantIdRef.current after buildLazyGetters
+     * makes previously-undefined options become defined — the core fix for
+     * warm-pool pods where PLATFORM_ASSISTANT_ID is empty at CES startup.
+     */
+
+    // GIVEN an API key is available but assistant ID is empty (warm-pool startup)
+    const apiKeyRef: ApiKeyRef = { current: "vak_test_key" };
+    const assistantIdRef: AssistantIdRef = { current: "" };
+    const { getManagedSubjectOptions, getManagedMaterializerOptions } =
+      buildLazyGetters({
+        platformBaseUrl: "https://api.vellum.ai",
+        assistantIdRef,
+        apiKeyRef,
+      });
+
+    // WHEN options are checked before assistant ID arrives
+    // THEN they are undefined
+    expect(getManagedSubjectOptions()).toBeUndefined();
+    expect(getManagedMaterializerOptions()).toBeUndefined();
+
+    // WHEN the assistant ID arrives via handshake/RPC
+    assistantIdRef.current = "ast_provisioned_123";
+
+    // THEN the same getter functions now return valid options
+    const subOpts = getManagedSubjectOptions();
+    expect(subOpts).toBeDefined();
+    expect(subOpts!.assistantId).toBe("ast_provisioned_123");
+    expect(subOpts!.assistantApiKey).toBe("vak_test_key");
+
+    const matOpts = getManagedMaterializerOptions();
+    expect(matOpts).toBeDefined();
+    expect(matOpts!.assistantId).toBe("ast_provisioned_123");
+  });
 });

package/src/managed-lazy-getters.ts

@@ -22,9 +22,19 @@ export interface ApiKeyRef {
   current: string;
 }
 
+/**
+ * Mutable reference to the platform assistant ID. For warm-pool pods the
+ * PLATFORM_ASSISTANT_ID env var is empty at startup; the assistant forwards
+ * the ID via the handshake or update_managed_credential RPC after
+ * provisioning, and `.current` is updated so lazy getters pick it up.
+ */
+export interface AssistantIdRef {
+  current: string;
+}
+
 export interface LazyGetterOptions {
   platformBaseUrl: string;
-  assistantId: string;
+  assistantIdRef: AssistantIdRef;
   apiKeyRef: ApiKeyRef;
   envApiKey?: string;
 }
@@ -43,22 +53,24 @@ export interface LazyGetters {
  * (chicken-and-egg: key is provisioned after hatch).
  */
 export function buildLazyGetters(opts: LazyGetterOptions): LazyGetters {
-  const { platformBaseUrl, assistantId, apiKeyRef, envApiKey } = opts;
+  const { platformBaseUrl, assistantIdRef, apiKeyRef, envApiKey } = opts;
 
   const getAssistantApiKey = (): string =>
     apiKeyRef.current || envApiKey || "";
 
   const getManagedSubjectOptions = (): ManagedSubjectResolverOptions | undefined => {
     const key = getAssistantApiKey();
-    return platformBaseUrl && key && assistantId
-      ? { platformBaseUrl, assistantApiKey: key, assistantId }
+    const id = assistantIdRef.current;
+    return platformBaseUrl && key && id
+      ? { platformBaseUrl, assistantApiKey: key, assistantId: id }
       : undefined;
   };
 
   const getManagedMaterializerOptions = (): ManagedMaterializerOptions | undefined => {
     const key = getAssistantApiKey();
-    return platformBaseUrl && key && assistantId
-      ? { platformBaseUrl, assistantApiKey: key, assistantId }
+    const id = assistantIdRef.current;
+    return platformBaseUrl && key && id
+      ? { platformBaseUrl, assistantApiKey: key, assistantId: id }
       : undefined;
   };
 

package/src/managed-main.ts

@@ -55,7 +55,7 @@ import { buildCesEgressHooks } from "./commands/egress-hooks.js";
 import { resolveManagedSubject } from "./subjects/managed.js";
 import { materializeManagedToken } from "./materializers/managed-platform.js";
 import { HandleType, parseHandle } from "@vellumai/ces-contracts";
-import { buildLazyGetters, type ApiKeyRef } from "./managed-lazy-getters.js";
+import { buildLazyGetters, type ApiKeyRef, type AssistantIdRef } from "./managed-lazy-getters.js";
 import { MANAGED_LOCAL_STATIC_REJECTION_ERROR } from "./managed-errors.js";
 import type { SecureKeyBackend } from "@vellumai/credential-storage";
 import { createLocalSecureKeyBackend } from "./materializers/local-secure-key-backend.js";
@@ -91,7 +91,7 @@ function ensureDataDirs(): void {
 // Build RPC handler registry (managed mode)
 // ---------------------------------------------------------------------------
 
-function buildHandlers(sessionIdRef: SessionIdRef, apiKeyRef: ApiKeyRef, secureKeyBackend: SecureKeyBackend): RpcHandlerRegistry {
+function buildHandlers(sessionIdRef: SessionIdRef, apiKeyRef: ApiKeyRef, assistantIdRef: AssistantIdRef, secureKeyBackend: SecureKeyBackend): RpcHandlerRegistry {
   // -- Grant stores ----------------------------------------------------------
   const persistentGrantStore = new PersistentGrantStore(
     getCesGrantsDir("managed"),
@@ -112,20 +112,19 @@ function buildHandlers(sessionIdRef: SessionIdRef, apiKeyRef: ApiKeyRef, secureK
   // We use a lazy getter so the handshake-provided key takes effect even
   // though handlers are built before the handshake completes.
   const platformBaseUrl = process.env["VELLUM_PLATFORM_URL"] ?? "";
-  const assistantId = process.env["PLATFORM_ASSISTANT_ID"] ?? "";
 
   const { getAssistantApiKey, getManagedSubjectOptions, getManagedMaterializerOptions } =
     buildLazyGetters({
       platformBaseUrl,
-      assistantId,
+      assistantIdRef,
       apiKeyRef,
       envApiKey: process.env["ASSISTANT_API_KEY"] || "",
     });
 
-  if (!platformBaseUrl || !assistantId) {
+  if (!platformBaseUrl) {
     warn(
-      "VELLUM_PLATFORM_URL and/or PLATFORM_ASSISTANT_ID not set. " +
-        "Managed credential materialisation will depend on the handshake-provided API key.",
+      "VELLUM_PLATFORM_URL not set. " +
+        "Managed credential materialisation will depend on the handshake-provided values.",
     );
   }
 
@@ -570,7 +569,8 @@ async function main(): Promise<void> {
   // are available to handlers at call time (after the handshake completes).
   const sessionIdRef: SessionIdRef = { current: `ces-managed-${Date.now()}` };
   const apiKeyRef: ApiKeyRef = { current: "" };
-  const handlers = buildHandlers(sessionIdRef, apiKeyRef, secureKeyBackend);
+  const assistantIdRef: AssistantIdRef = { current: process.env["PLATFORM_ASSISTANT_ID"] ?? "" };
+  const handlers = buildHandlers(sessionIdRef, apiKeyRef, assistantIdRef, secureKeyBackend);
 
   const server = new CesRpcServer({
     input: connection.readable,
@@ -585,16 +585,24 @@ async function main(): Promise<void> {
         process.stderr.write(`[ces-managed] ERROR: ${msg} ${args.map(String).join(" ")}\n`),
     },
     signal: controller.signal,
-    onHandshakeComplete: (hsSessionId, hsApiKey) => {
+    onHandshakeComplete: (hsSessionId, hsApiKey, hsAssistantId) => {
       sessionIdRef.current = hsSessionId;
       if (hsApiKey) {
         apiKeyRef.current = hsApiKey;
         log(`Received assistant API key via handshake`);
       }
+      if (hsAssistantId) {
+        assistantIdRef.current = hsAssistantId;
+        log(`Received assistant ID via handshake`);
+      }
     },
-    onApiKeyUpdate: (newKey) => {
+    onApiKeyUpdate: (newKey, newAssistantId) => {
       apiKeyRef.current = newKey;
       log(`Assistant API key updated via RPC`);
+      if (newAssistantId) {
+        assistantIdRef.current = newAssistantId;
+        log(`Assistant ID updated via RPC`);
+      }
     },
   });
 

package/src/server.ts

@@ -88,10 +88,10 @@ export interface CesServerOptions {
   logger?: Pick<Console, "log" | "warn" | "error">;
   /** Optional abort signal to shut down the server. */
   signal?: AbortSignal;
-  /** Callback invoked when the handshake completes with the negotiated session ID and optional API key. */
-  onHandshakeComplete?: (sessionId: string, assistantApiKey?: string) => void;
-  /** Callback invoked when the assistant pushes an updated API key after hatch. */
-  onApiKeyUpdate?: (assistantApiKey: string) => void;
+  /** Callback invoked when the handshake completes with the negotiated session ID and optional API key / assistant ID. */
+  onHandshakeComplete?: (sessionId: string, assistantApiKey?: string, assistantId?: string) => void;
+  /** Callback invoked when the assistant pushes an updated API key (and optionally assistant ID) after hatch. */
+  onApiKeyUpdate?: (assistantApiKey: string, assistantId?: string) => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -104,7 +104,7 @@ export class CesRpcServer {
   private readonly handlers: RpcHandlerRegistry;
   private readonly logger: Pick<Console, "log" | "warn" | "error">;
   private readonly signal?: AbortSignal;
-  private readonly onHandshakeComplete?: (sessionId: string, assistantApiKey?: string) => void;
+  private readonly onHandshakeComplete?: (sessionId: string, assistantApiKey?: string, assistantId?: string) => void;
 
   private handshakeComplete = false;
   private sessionId: string | null = null;
@@ -123,8 +123,8 @@ export class CesRpcServer {
     if (options.onApiKeyUpdate) {
       const onUpdate = options.onApiKeyUpdate;
       this.handlers[CesRpcMethod.UpdateManagedCredential] = (request: unknown) => {
-        const { assistantApiKey } = request as { assistantApiKey: string };
-        onUpdate(assistantApiKey);
+        const { assistantApiKey, assistantId } = request as { assistantApiKey: string; assistantId?: string };
+        onUpdate(assistantApiKey, assistantId);
         return { updated: true };
       };
     }
@@ -267,7 +267,7 @@ export class CesRpcServer {
       this.handshakeComplete = true;
       this.sessionId = req.sessionId;
       this.logger.log(`[ces-server] Handshake accepted for session ${req.sessionId}`);
-      this.onHandshakeComplete?.(req.sessionId, req.assistantApiKey);
+      this.onHandshakeComplete?.(req.sessionId, req.assistantApiKey, req.assistantId);
     } else {
       this.logger.warn(
         `[ces-server] Handshake rejected: version mismatch (got ${req.protocolVersion}, expected ${CES_PROTOCOL_VERSION})`,