@vellumai/credential-executor 0.10.7-dev.202607102035.64f07ea → 0.10.7-staging.1

package/src/managed-errors.ts

@@ -0,0 +1,9 @@
+/**
+ * Error message constants for managed-mode CES.
+ *
+ * Re-exported from @vellumai/service-contracts so both the assistant and
+ * credential-executor can share the constant via the approved shared-code
+ * path without violating the hard process-boundary isolation.
+ */
+
+export { MANAGED_LOCAL_STATIC_REJECTION_ERROR } from "@vellumai/service-contracts/credential-rpc";

package/src/managed-lazy-getters.ts

@@ -0,0 +1,106 @@
+/**
+ * Lazy getter pattern for managed CES API key propagation.
+ *
+ * In managed mode the assistant API key may arrive after CES handlers are
+ * registered (via the handshake callback or a later RPC update). The
+ * `ApiKeyRef` + `buildLazyGetters` pattern allows handlers to resolve
+ * the key at call time rather than at registration time.
+ *
+ * Extracted from `managed-main.ts` so the behavioral contract can be
+ * tested directly without exercising the full managed bootstrap lifecycle.
+ */
+
+import type { ManagedSubjectResolverOptions } from "./subjects/managed.js";
+import type { ManagedMaterializerOptions } from "./materializers/managed-platform.js";
+
+/**
+ * Mutable reference to the assistant API key. Allows the handshake callback
+ * to inject the key provisioned at runtime (which arrives after handlers are
+ * built). Handlers read `.current` at call time, not at registration time.
+ */
+export interface ApiKeyRef {
+  current: string;
+}
+
+/**
+ * Mutable reference to the platform assistant ID. The assistant ID is not
+ * available at CES startup (warm-pool pods); the assistant forwards it 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;
+}
+
+/**
+ * Overwrite the session-scoped managed credential refs.
+ *
+ * The managed handler registry is long-lived — it persists across assistant
+ * reconnects — so every handshake and every `update_managed_credential` must
+ * fully overwrite these refs, including clearing them when a value is absent.
+ * Otherwise a new or reprovisioned session could keep materializing platform
+ * credentials with the previous session's API key or assistant ID. Absent
+ * values fall back to "" (fail closed): the lazy getters then return no
+ * materialization options, and `getAssistantApiKey` falls back to the env key.
+ */
+export function applyManagedCredentialRefs(
+  apiKeyRef: ApiKeyRef,
+  assistantIdRef: AssistantIdRef,
+  apiKey: string | undefined,
+  assistantId: string | undefined,
+): void {
+  apiKeyRef.current = apiKey ?? "";
+  assistantIdRef.current = assistantId ?? "";
+}
+
+export interface LazyGetterOptions {
+  platformBaseUrl: string;
+  assistantIdRef: AssistantIdRef;
+  apiKeyRef: ApiKeyRef;
+  envApiKey?: string;
+}
+
+export interface LazyGetters {
+  getAssistantApiKey: () => string;
+  getManagedSubjectOptions: () => ManagedSubjectResolverOptions | undefined;
+  getManagedMaterializerOptions: () => ManagedMaterializerOptions | undefined;
+}
+
+/**
+ * Build lazy getter functions that resolve the API key at call time.
+ *
+ * Prefers the handshake-provided key (via `apiKeyRef.current`) over the
+ * env-var fallback, since in managed mode the env var may not be set
+ * (chicken-and-egg: key is provisioned after hatch).
+ */
+export function buildLazyGetters(opts: LazyGetterOptions): LazyGetters {
+  const { platformBaseUrl, assistantIdRef, apiKeyRef, envApiKey } = opts;
+
+  const getAssistantApiKey = (): string => apiKeyRef.current || envApiKey || "";
+
+  const getManagedSubjectOptions = ():
+    | ManagedSubjectResolverOptions
+    | undefined => {
+    const key = getAssistantApiKey();
+    const id = assistantIdRef.current;
+    return platformBaseUrl && key && id
+      ? { platformBaseUrl, assistantApiKey: key, assistantId: id }
+      : undefined;
+  };
+
+  const getManagedMaterializerOptions = ():
+    | ManagedMaterializerOptions
+    | undefined => {
+    const key = getAssistantApiKey();
+    const id = assistantIdRef.current;
+    return platformBaseUrl && key && id
+      ? { platformBaseUrl, assistantApiKey: key, assistantId: id }
+      : undefined;
+  };
+
+  return {
+    getAssistantApiKey,
+    getManagedSubjectOptions,
+    getManagedMaterializerOptions,
+  };
+}