@vellumai/credential-executor 0.5.11 → 0.5.13

package/node_modules/@vellumai/ces-contracts/src/__tests__/grants.test.ts

@@ -71,19 +71,19 @@ describe("handles", () => {
 
   describe("localOAuthHandle", () => {
     test("constructs the expected format", () => {
-      expect(localOAuthHandle("integration:google", "conn-123")).toBe(
-        "local_oauth:integration:google/conn-123",
+      expect(localOAuthHandle("google", "conn-123")).toBe(
+        "local_oauth:google/conn-123",
       );
     });
 
-    test("roundtrips with integration: prefix in providerKey", () => {
-      const raw = localOAuthHandle("integration:slack", "conn-abc");
+    test("roundtrips through parseHandle", () => {
+      const raw = localOAuthHandle("slack", "conn-abc");
       const result = parseHandle(raw);
       expect(result.ok).toBe(true);
       if (!result.ok) return;
       expect(result.handle.type).toBe(HandleType.LocalOAuth);
       if (result.handle.type !== HandleType.LocalOAuth) return;
-      expect(result.handle.providerKey).toBe("integration:slack");
+      expect(result.handle.providerKey).toBe("slack");
       expect(result.handle.connectionId).toBe("conn-abc");
     });
   });
@@ -133,7 +133,7 @@ describe("handles", () => {
     });
 
     test("rejects local_oauth with no slash", () => {
-      const result = parseHandle("local_oauth:integration:google");
+      const result = parseHandle("local_oauth:google");
       expect(result.ok).toBe(false);
     });
 
@@ -150,7 +150,7 @@ describe("handles", () => {
       ).not.toThrow();
       expect(() =>
         CredentialHandleSchema.parse(
-          "local_oauth:integration:google/conn-1",
+          "local_oauth:google/conn-1",
         ),
       ).not.toThrow();
       expect(() =>

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

@@ -13,7 +13,7 @@
  *
  * 2. **Local OAuth** — references a locally persisted OAuth connection.
  *    Format: `local_oauth:<providerKey>/<connectionId>` where providerKey
- *    uses the existing `integration:*` keys (e.g. `integration:google`).
+ *    is the bare provider name (e.g. `google`).
  *
  * 3. **Managed OAuth** — references an OAuth connection managed by the
  *    platform. Format: `platform_oauth:<connectionId>` where connectionId
@@ -50,7 +50,7 @@ export interface LocalStaticHandle {
 
 export interface LocalOAuthHandle {
   type: typeof HandleType.LocalOAuth;
-  /** Provider key (e.g. "integration:google", "integration:slack"). */
+  /** Provider key (e.g. "google", "slack"). */
   providerKey: string;
   /** Connection identifier. */
   connectionId: string;
@@ -146,8 +146,9 @@ export function parseHandle(raw: string): ParseHandleResult {
     }
 
     case HandleType.LocalOAuth: {
-      // providerKey may itself contain a colon (e.g. "integration:google"),
-      // so we split on the *last* "/" to separate providerKey from connectionId.
+      // providerKey is typically a bare name (e.g. "google"), but legacy handles
+      // may contain a colon (e.g. "integration:google"), so we split on the
+      // *last* "/" to separate providerKey from connectionId.
       const lastSlashIdx = rest.lastIndexOf("/");
       if (
         lastSlashIdx === -1 ||

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/node_modules/@vellumai/credential-storage/src/index.ts

@@ -98,7 +98,7 @@ export interface SecureKeyBackend {
 export interface OAuthConnectionRecord {
   /** Unique identifier for this connection. */
   id: string;
-  /** Provider key (e.g. "integration:google", "integration:slack"). */
+  /** Provider key (e.g. "google", "slack"). */
   providerKey: string;
   /** Account identifier (e.g. email address). */
   accountInfo: string | null;

package/package.json

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

package/src/__tests__/command-executor.test.ts

@@ -1482,7 +1482,7 @@ describe("executeAuthenticatedCommand — integration: local OAuth", () => {
     });
     addCommandGrant(
       deps.persistentStore,
-      "local_oauth:integration:google/conn-123",
+      "local_oauth:google/conn-123",
       digest,
       "list",
     );
@@ -1490,7 +1490,7 @@ describe("executeAuthenticatedCommand — integration: local OAuth", () => {
     const request: ExecuteCommandRequest = {
       bundleDigest: digest,
       profileName: "list",
-      credentialHandle: "local_oauth:integration:google/conn-123",
+      credentialHandle: "local_oauth:google/conn-123",
       argv: ["list", "--format", "json"],
       workspaceDir: testWorkspaceDir,
       purpose: "OAuth pipeline test",

package/src/__tests__/http-executor.test.ts

@@ -102,7 +102,7 @@ function buildOAuthConnection(
 ): OAuthConnectionRecord {
   return {
     id: overrides.id ?? "conn-uuid-1",
-    providerKey: overrides.providerKey ?? "integration:google",
+    providerKey: overrides.providerKey ?? "google",
     accountInfo: overrides.accountInfo ?? "user@example.com",
     grantedScopes: overrides.grantedScopes ?? ["openid", "email"],
     accessTokenPath: overrides.accessTokenPath ??
@@ -434,7 +434,7 @@ describe("HTTP executor: local OAuth", () => {
   beforeEach(() => {
     connection = buildOAuthConnection({
       id: "conn-google-1",
-      providerKey: "integration:google",
+      providerKey: "google",
       expiresAt: Date.now() + 3600000, // valid for 1 hour
     });
 
@@ -451,7 +451,7 @@ describe("HTTP executor: local OAuth", () => {
   });
 
   test("successful OAuth request with matching grant", async () => {
-    const handle = localOAuthHandle("integration:google", "conn-google-1");
+    const handle = localOAuthHandle("google", "conn-google-1");
 
     fixture.persistentStore.add({
       id: "grant-google-calendar",
@@ -492,7 +492,7 @@ describe("HTTP executor: local OAuth", () => {
   });
 
   test("OAuth token scrubbed from response body", async () => {
-    const handle = localOAuthHandle("integration:google", "conn-google-1");
+    const handle = localOAuthHandle("google", "conn-google-1");
 
     fixture.persistentStore.add({
       id: "grant-google-debug",

package/src/__tests__/local-materializers.test.ts

@@ -98,7 +98,7 @@ function buildOAuthConnection(
 ): OAuthConnectionRecord {
   return {
     id: overrides.id ?? "conn-uuid-1",
-    providerKey: overrides.providerKey ?? "integration:google",
+    providerKey: overrides.providerKey ?? "google",
     accountInfo: overrides.accountInfo ?? "user@example.com",
     grantedScopes: overrides.grantedScopes ?? ["openid", "email"],
     accessTokenPath: overrides.accessTokenPath ??
@@ -227,10 +227,10 @@ describe("local OAuth subject resolution", () => {
   test("resolves a valid OAuth handle to an OAuth subject", () => {
     const conn = buildOAuthConnection({
       id: "conn-abc",
-      providerKey: "integration:google",
+      providerKey: "google",
     });
     const deps = createResolverDeps({ oauthConnections: [conn] });
-    const handle = localOAuthHandle("integration:google", "conn-abc");
+    const handle = localOAuthHandle("google", "conn-abc");
 
     const result = resolveLocalSubject(handle, deps);
 
@@ -239,12 +239,12 @@ describe("local OAuth subject resolution", () => {
     expect(result.subject.type).toBe(HandleType.LocalOAuth);
     if (result.subject.type !== HandleType.LocalOAuth) return;
     expect(result.subject.connection.id).toBe("conn-abc");
-    expect(result.subject.connection.providerKey).toBe("integration:google");
+    expect(result.subject.connection.providerKey).toBe("google");
   });
 
   test("fails when the connection does not exist", () => {
     const deps = createResolverDeps({ oauthConnections: [] });
-    const handle = localOAuthHandle("integration:google", "missing-conn");
+    const handle = localOAuthHandle("google", "missing-conn");
 
     const result = resolveLocalSubject(handle, deps);
 
@@ -257,19 +257,19 @@ describe("local OAuth subject resolution", () => {
   test("fails when provider key in handle does not match connection", () => {
     const conn = buildOAuthConnection({
       id: "conn-xyz",
-      providerKey: "integration:slack",
+      providerKey: "slack",
     });
     const deps = createResolverDeps({ oauthConnections: [conn] });
     // Handle says google but connection is slack
-    const handle = localOAuthHandle("integration:google", "conn-xyz");
+    const handle = localOAuthHandle("google", "conn-xyz");
 
     const result = resolveLocalSubject(handle, deps);
 
     expect(result.ok).toBe(false);
     if (result.ok) return;
     expect(result.error).toMatch(/providerKey/);
-    expect(result.error).toMatch(/integration:slack/);
-    expect(result.error).toMatch(/integration:google/);
+    expect(result.error).toMatch(/slack/);
+    expect(result.error).toMatch(/google/);
   });
 });
 
@@ -378,13 +378,13 @@ describe("OAuth token materialisation", () => {
   test("materialises a valid non-expired access token", async () => {
     const conn = buildOAuthConnection({
       id: "conn-1",
-      providerKey: "integration:google",
+      providerKey: "google",
       // Token expires in the future (1 hour from now)
       expiresAt: Date.now() + 60 * 60 * 1000,
       hasRefreshToken: true,
     });
     const deps = createResolverDeps({ oauthConnections: [conn] });
-    const handle = localOAuthHandle("integration:google", "conn-1");
+    const handle = localOAuthHandle("google", "conn-1");
 
     const resolved = resolveLocalSubject(handle, deps);
     expect(resolved.ok).toBe(true);
@@ -408,11 +408,11 @@ describe("OAuth token materialisation", () => {
   test("fails when no access token is stored (disconnected connection)", async () => {
     const conn = buildOAuthConnection({
       id: "conn-disconnected",
-      providerKey: "integration:slack",
+      providerKey: "slack",
       hasRefreshToken: false,
     });
     const deps = createResolverDeps({ oauthConnections: [conn] });
-    const handle = localOAuthHandle("integration:slack", "conn-disconnected");
+    const handle = localOAuthHandle("slack", "conn-disconnected");
 
     const resolved = resolveLocalSubject(handle, deps);
     expect(resolved.ok).toBe(true);
@@ -435,14 +435,14 @@ describe("OAuth token materialisation", () => {
   test("fails when token is expired and hasRefreshToken is false", async () => {
     const conn = buildOAuthConnection({
       id: "conn-expired-no-refresh",
-      providerKey: "integration:google",
+      providerKey: "google",
       // Token expired 10 minutes ago
       expiresAt: Date.now() - 10 * 60 * 1000,
       hasRefreshToken: false,
     });
     const deps = createResolverDeps({ oauthConnections: [conn] });
     const handle = localOAuthHandle(
-      "integration:google",
+      "google",
       "conn-expired-no-refresh",
     );
 
@@ -469,12 +469,12 @@ describe("OAuth token materialisation", () => {
   test("materialises a token with null expiresAt (no expiry info)", async () => {
     const conn = buildOAuthConnection({
       id: "conn-noexpiry",
-      providerKey: "integration:github",
+      providerKey: "github",
       expiresAt: null,
       hasRefreshToken: false,
     });
     const deps = createResolverDeps({ oauthConnections: [conn] });
-    const handle = localOAuthHandle("integration:github", "conn-noexpiry");
+    const handle = localOAuthHandle("github", "conn-noexpiry");
 
     const resolved = resolveLocalSubject(handle, deps);
     expect(resolved.ok).toBe(true);
@@ -504,13 +504,13 @@ describe("OAuth refresh-on-expiry", () => {
   test("refreshes an expired token and returns the new access token", async () => {
     const conn = buildOAuthConnection({
       id: "conn-expired",
-      providerKey: "integration:google",
+      providerKey: "google",
       // Token expired 10 minutes ago
       expiresAt: Date.now() - 10 * 60 * 1000,
       hasRefreshToken: true,
     });
     const deps = createResolverDeps({ oauthConnections: [conn] });
-    const handle = localOAuthHandle("integration:google", "conn-expired");
+    const handle = localOAuthHandle("google", "conn-expired");
 
     const resolved = resolveLocalSubject(handle, deps);
     expect(resolved.ok).toBe(true);
@@ -545,12 +545,12 @@ describe("OAuth refresh-on-expiry", () => {
   test("fails when token is expired but no refresh function is configured", async () => {
     const conn = buildOAuthConnection({
       id: "conn-no-refresh-fn",
-      providerKey: "integration:google",
+      providerKey: "google",
       expiresAt: Date.now() - 10 * 60 * 1000,
       hasRefreshToken: true,
     });
     const deps = createResolverDeps({ oauthConnections: [conn] });
-    const handle = localOAuthHandle("integration:google", "conn-no-refresh-fn");
+    const handle = localOAuthHandle("google", "conn-no-refresh-fn");
 
     const resolved = resolveLocalSubject(handle, deps);
     expect(resolved.ok).toBe(true);
@@ -577,13 +577,13 @@ describe("OAuth refresh-on-expiry", () => {
   test("fails when token is expired and no refresh token is stored", async () => {
     const conn = buildOAuthConnection({
       id: "conn-no-stored-refresh",
-      providerKey: "integration:google",
+      providerKey: "google",
       expiresAt: Date.now() - 10 * 60 * 1000,
       hasRefreshToken: true,
     });
     const deps = createResolverDeps({ oauthConnections: [conn] });
     const handle = localOAuthHandle(
-      "integration:google",
+      "google",
       "conn-no-stored-refresh",
     );
 
@@ -617,13 +617,13 @@ describe("OAuth refresh-on-expiry", () => {
   test("fails when refresh function returns a failure result", async () => {
     const conn = buildOAuthConnection({
       id: "conn-refresh-fail",
-      providerKey: "integration:google",
+      providerKey: "google",
       expiresAt: Date.now() - 10 * 60 * 1000,
       hasRefreshToken: true,
     });
     const deps = createResolverDeps({ oauthConnections: [conn] });
     const handle = localOAuthHandle(
-      "integration:google",
+      "google",
       "conn-refresh-fail",
     );
 
@@ -662,12 +662,12 @@ describe("refresh circuit breaker", () => {
   test("trips after repeated refresh failures and returns error", async () => {
     const conn = buildOAuthConnection({
       id: "conn-breaker",
-      providerKey: "integration:google",
+      providerKey: "google",
       expiresAt: Date.now() - 10 * 60 * 1000,
       hasRefreshToken: true,
     });
     const deps = createResolverDeps({ oauthConnections: [conn] });
-    const handle = localOAuthHandle("integration:google", "conn-breaker");
+    const handle = localOAuthHandle("google", "conn-breaker");
 
     const resolved = resolveLocalSubject(handle, deps);
     expect(resolved.ok).toBe(true);
@@ -724,7 +724,7 @@ describe("deterministic fail-closed behaviour", () => {
 
     // Missing OAuth connection
     const r3 = resolveLocalSubject(
-      localOAuthHandle("integration:x", "missing-conn"),
+      localOAuthHandle("x", "missing-conn"),
       deps,
     );
     expect(r3.ok).toBe(false);
@@ -765,10 +765,10 @@ describe("deterministic fail-closed behaviour", () => {
   test("OAuth disconnection detected before any refresh attempt", async () => {
     const conn = buildOAuthConnection({
       id: "conn-disco",
-      providerKey: "integration:slack",
+      providerKey: "slack",
     });
     const deps = createResolverDeps({ oauthConnections: [conn] });
-    const handle = localOAuthHandle("integration:slack", "conn-disco");
+    const handle = localOAuthHandle("slack", "conn-disco");
 
     const resolved = resolveLocalSubject(handle, deps);
     expect(resolved.ok).toBe(true);
@@ -831,12 +831,12 @@ describe("end-to-end local materialisation", () => {
   test("full pipeline: resolve OAuth handle -> materialise token", async () => {
     const conn = buildOAuthConnection({
       id: "conn-e2e",
-      providerKey: "integration:linear",
+      providerKey: "linear",
       expiresAt: Date.now() + 3600 * 1000,
       hasRefreshToken: true,
     });
     const deps = createResolverDeps({ oauthConnections: [conn] });
-    const handle = localOAuthHandle("integration:linear", "conn-e2e");
+    const handle = localOAuthHandle("linear", "conn-e2e");
 
     // Step 1: Resolve
     const resolved = resolveLocalSubject(handle, deps);

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/__tests__/managed-materializers.test.ts

@@ -264,7 +264,7 @@ describe("resolveManagedSubject", () => {
 
   test("rejects a local_oauth handle", async () => {
     const result = await resolveManagedSubject(
-      "local_oauth:integration:google/conn_local1",
+      "local_oauth:google/conn_local1",
       {
         platformBaseUrl: TEST_PLATFORM_URL,
         assistantApiKey: TEST_API_KEY,

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})`,