@evomap/evolver-proxy 2.0.0-beta.2 → 2.0.0-beta.22

package/dist/llm/upstream.js

@@ -32,6 +32,56 @@ async function loadDefaultBedrockRuntime() {
 function isOpenAiMode(upstreamMode) {
     return upstreamMode === 'openai';
 }
+/**
+ * Detect deprecated OPENAI_COMPATIBLE_BASE_URLS env var (#671).
+ * V1 multi-base lists are ignored for routing; V2 OpenAI base must pass *.api.openai.com/v1 allowlist
+ * via EVOLVER_LLM_OPENAI_BASE_URL / EVOMAP_OPENAI_BASE_URL / OPENAI_BASE_URL.
+ * Warn once per process to avoid per-request spam.
+ */
+let warnedDeprecatedOpenAICompatible = false;
+function hasDeprecatedOpenAICompatibleConfig(env) {
+    return [
+        env['EVOLVER_OPENAI_COMPATIBLE_BASE_URLS'],
+        env['EVOMAP_OPENAI_COMPATIBLE_BASE_URLS'],
+    ].some((value) => typeof value === 'string' && value.trim() !== '');
+}
+function explicitOpenAIBaseUrl(env) {
+    return env['EVOLVER_LLM_OPENAI_BASE_URL'] || env['EVOMAP_OPENAI_BASE_URL'] || env['OPENAI_BASE_URL'];
+}
+function hasCanonicalOpenAIMigrationPair(env) {
+    const baseUrl = env['EVOLVER_LLM_OPENAI_BASE_URL']?.trim();
+    if (!baseUrl || !env['EVOLVER_LLM_OPENAI_API_KEY']?.trim())
+        return false;
+    try {
+        normalizeOpenAIBaseUrl(baseUrl);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function warnDeprecatedOpenAICompatible(env) {
+    if (!hasDeprecatedOpenAICompatibleConfig(env) || warnedDeprecatedOpenAICompatible)
+        return;
+    warnedDeprecatedOpenAICompatible = true;
+    console.warn('[proxy] DEPRECATED: EVOMAP_OPENAI_COMPATIBLE_BASE_URLS / EVOLVER_OPENAI_COMPATIBLE_BASE_URLS is ignored for routing. ' +
+        'Manual migration is required: explicitly bind one official https://*.api.openai.com/v1 endpoint and its credential ' +
+        'with EVOLVER_LLM_OPENAI_BASE_URL and EVOLVER_LLM_OPENAI_API_KEY. ' +
+        'LiteLLM, OpenRouter, Azure OpenAI, MiniMax, DeepSeek, Moonshot, and other custom OpenAI-compatible hosts have no drop-in V2 route. ' +
+        'Do not reuse their credentials as an OpenAI credential; keep that workload outside this proxy until a supported provider-specific route exists.');
+}
+function assertDeprecatedOpenAICompatibleMigrated(env) {
+    warnDeprecatedOpenAICompatible(env);
+    if (hasDeprecatedOpenAICompatibleConfig(env) && !hasCanonicalOpenAIMigrationPair(env)) {
+        throw new Error('[proxy] manual migration of deprecated OpenAI-compatible base URLs requires an explicit '
+            + 'EVOLVER_LLM_OPENAI_BASE_URL and '
+            + 'EVOLVER_LLM_OPENAI_API_KEY migration pair before the OpenAI route can start');
+    }
+}
+/** Test helper: reset once-warn latch (unit tests only). */
+function resetDeprecatedOpenAICompatibleWarning() {
+    warnedDeprecatedOpenAICompatible = false;
+}
 function isAllowedOpenAIHostname(hostname) {
     const h = hostname.toLowerCase();
     return h === 'api.openai.com' || h.endsWith('.api.openai.com');
@@ -56,8 +106,23 @@ function normalizeOpenAIBaseUrl(raw) {
     }
     return value;
 }
+function openAIBaseUrlIdentity(raw) {
+    return new URL(normalizeOpenAIBaseUrl(raw)).href;
+}
+function assertDeprecatedOpenAIRequestBaseBound(env, requestBaseUrl) {
+    if (!requestBaseUrl || !hasDeprecatedOpenAICompatibleConfig(env))
+        return;
+    const canonicalBaseUrl = env['EVOLVER_LLM_OPENAI_BASE_URL'];
+    if (typeof canonicalBaseUrl !== 'string'
+        || openAIBaseUrlIdentity(requestBaseUrl) !== openAIBaseUrlIdentity(canonicalBaseUrl)) {
+        throw new Error('[proxy] request-scoped OpenAI base URL must match EVOLVER_LLM_OPENAI_BASE_URL '
+            + 'while deprecated OpenAI-compatible routing remains configured');
+    }
+}
 export function resolveOpenAIUpstreamUrl(env = process.env) {
-    return normalizeOpenAIBaseUrl(env['EVOLVER_LLM_OPENAI_BASE_URL'] || env['EVOMAP_OPENAI_BASE_URL'] || env['OPENAI_BASE_URL'] || DEFAULT_OPENAI_UPSTREAM_URL);
+    assertDeprecatedOpenAICompatibleMigrated(env);
+    const explicitBaseUrl = explicitOpenAIBaseUrl(env);
+    return normalizeOpenAIBaseUrl(explicitBaseUrl || DEFAULT_OPENAI_UPSTREAM_URL);
 }
 function pathForOpenAIBase(path) {
     if (path === '/v1')
@@ -456,6 +521,10 @@ export function makeOpenAIUpstream(opts = {}) {
     const headersTimeoutMs = opts.headersTimeoutMs ?? DEFAULT_HEADERS_TIMEOUT_MS;
     return async (path, body, callOpts) => {
         const env = opts.env ?? process.env;
+        // A request-scoped base override is routing data, not evidence that the daemon's
+        // legacy provider credential/base pair was deliberately migrated.
+        assertDeprecatedOpenAICompatibleMigrated(env);
+        assertDeprecatedOpenAIRequestBaseBound(env, callOpts.baseUrl);
         const baseUrl = callOpts.baseUrl ? normalizeOpenAIBaseUrl(callOpts.baseUrl) : resolveOpenAIUpstreamUrl(env);
         return fetchUpstream(`${baseUrl}${path}`, body, callOpts, buildOpenAIHeaders(callOpts.inboundHeaders, env), fetchImpl, headersTimeoutMs, 'openai', (headers) => contentTypeIncludes(headers, 'text/event-stream'));
     };
@@ -488,4 +557,5 @@ export function makeVertexUpstream(opts = {}) {
         const env = opts.env ?? process.env;
         return fetchUpstream(`${baseUrl}${path}`, body, callOpts, buildVertexHeaders(env), fetchImpl, headersTimeoutMs, 'vertex', (headers, endpoint) => contentTypeIncludes(headers, 'text/event-stream') || /:streamGenerateContent(\b|\?|$)/.test(endpoint));
     };
-}
+}
+export { warnDeprecatedOpenAICompatible, resetDeprecatedOpenAICompatibleWarning };

package/dist/private/accountAssetCompatibility.d.ts

@@ -0,0 +1,29 @@
+import type { hub } from '@evomap/evolver-core';
+import { type AccountAssetListOptions, type AccountAssetListResult } from '@evomap/evolver-adapter-public';
+export interface PrivateAccountAssetHub {
+    listAccountAssets(opts: AccountAssetListOptions): Promise<AccountAssetListResult>;
+}
+interface PrivateCompatibilityResponse {
+    status: number;
+    json(): Promise<unknown>;
+}
+export type PrivateCompatibilityFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<PrivateCompatibilityResponse>;
+interface PrivateAccountAssetCompatibilityOptions {
+    baseUrl: string;
+    auth: hub.AuthProvider;
+    senderId: () => string | undefined;
+    env: Record<string, string | undefined>;
+    fetchFn?: PrivateCompatibilityFetch;
+}
+/**
+ * Older official private adapters predate account inventory listing. Keep the
+ * compatibility wire at the private composition edge, and never replace a
+ * future adapter's native implementation.
+ */
+export declare function withPrivateAccountAssetCompatibility<T extends object>(hubCapability: T, opts: PrivateAccountAssetCompatibilityOptions): T & PrivateAccountAssetHub;
+export declare function normalizePrivateHubBaseUrl(raw: string, env: Record<string, string | undefined>): string;
+export {};

package/dist/private/accountAssetCompatibility.js

@@ -0,0 +1,196 @@
+import { AuthError, HubClientError, HubUnreachableError, } from '@evomap/evolver-adapter-public';
+const PRIVATE_PUBLISHED_ASSETS_PATH = '/a2a/assets/published-by-me';
+const PRIVATE_PUBLISHED_MAX_PAGE_SIZE = 500;
+const PRIVATE_CURSOR_MAX_LENGTH = 4096;
+/**
+ * Older official private adapters predate account inventory listing. Keep the
+ * compatibility wire at the private composition edge, and never replace a
+ * future adapter's native implementation.
+ */
+export function withPrivateAccountAssetCompatibility(hubCapability, opts) {
+    const candidate = hubCapability;
+    if (typeof candidate['listAccountAssets'] === 'function') {
+        return hubCapability;
+    }
+    if (candidate['listAccountAssets'] !== undefined) {
+        throw new Error('private Hub adapter exposes an invalid account asset sync capability');
+    }
+    const client = new PrivateAccountAssetCompatibility(opts);
+    try {
+        Object.defineProperty(hubCapability, 'listAccountAssets', {
+            configurable: false,
+            enumerable: false,
+            writable: false,
+            value: (listOpts) => client.list(listOpts),
+        });
+    }
+    catch {
+        throw new Error('private Hub adapter cannot be extended with account asset sync compatibility');
+    }
+    return hubCapability;
+}
+class PrivateAccountAssetCompatibility {
+    opts;
+    baseUrl;
+    fetchFn;
+    constructor(opts) {
+        this.opts = opts;
+        this.baseUrl = normalizePrivateHubBaseUrl(opts.baseUrl, opts.env);
+        this.fetchFn = opts.fetchFn ?? globalPrivateCompatibilityFetch;
+    }
+    async list(opts) {
+        assertAccountAssetListOptions(opts);
+        if (opts.scope === 'purchased') {
+            // Private Hub has no marketplace/purchase ledger. An empty inventory is
+            // distinct from published assets and avoids importing arbitrary recall hits.
+            if (opts.cursor)
+                throw new HubClientError(400, { code: 'private_marketplace_cursor_unsupported' });
+            return { assets: [], count: 0, hasMore: false };
+        }
+        const limit = Math.min(opts.limit ?? 100, PRIVATE_PUBLISHED_MAX_PAGE_SIZE);
+        const query = new URLSearchParams({ limit: String(limit) });
+        const senderId = this.opts.senderId()?.trim();
+        if (senderId)
+            query.set('sender_id', senderId);
+        if (opts.cursor)
+            query.set('cursor', opts.cursor);
+        if (opts.type)
+            query.set('type', opts.type);
+        if (opts.status && opts.status !== 'all')
+            query.set('status', opts.status);
+        const signed = await this.opts.auth.authenticate({ method: 'GET', path: PRIVATE_PUBLISHED_ASSETS_PATH });
+        const headers = accountAssetHeaders(signed);
+        const url = `${this.baseUrl}${PRIVATE_PUBLISHED_ASSETS_PATH}?${query.toString()}`;
+        assertPrivateCompatibilityUrlSecure(url, this.opts.env);
+        let response;
+        try {
+            response = await this.fetchFn(url, { method: 'GET', headers });
+        }
+        catch (error) {
+            if (error instanceof AuthError || error instanceof HubClientError || error instanceof HubUnreachableError)
+                throw error;
+            throw new HubUnreachableError('Private Hub account asset request failed before a response arrived', {
+                context: `GET ${PRIVATE_PUBLISHED_ASSETS_PATH}`,
+            });
+        }
+        const body = await parseCompatibilityResponse(response);
+        if (response.status === 401 || response.status === 403)
+            throw new AuthError(response.status, body);
+        if (response.status >= 400 && response.status < 500)
+            throw new HubClientError(response.status, body);
+        if (response.status >= 500)
+            throw new Error(`private hub ${response.status} ${PRIVATE_PUBLISHED_ASSETS_PATH}`);
+        return parsePublishedPage(body, limit);
+    }
+}
+function assertAccountAssetListOptions(opts) {
+    if (!opts || (opts.scope !== 'purchased' && opts.scope !== 'published')) {
+        throw new HubClientError(400, { code: 'invalid_account_asset_scope' });
+    }
+    if (opts.limit !== undefined && (!Number.isSafeInteger(opts.limit) || opts.limit <= 0)) {
+        throw new HubClientError(400, { code: 'invalid_account_asset_limit' });
+    }
+    if (opts.cursor !== undefined && (!opts.cursor.trim() || opts.cursor.length > PRIVATE_CURSOR_MAX_LENGTH)) {
+        throw new HubClientError(400, { code: 'invalid_account_asset_cursor' });
+    }
+    if (opts.type !== undefined && opts.type !== 'Gene' && opts.type !== 'Capsule') {
+        throw new HubClientError(400, { code: 'invalid_account_asset_type' });
+    }
+    if (opts.status !== undefined && opts.status !== 'draft' && opts.status !== 'promoted' && opts.status !== 'all') {
+        throw new HubClientError(400, { code: 'invalid_account_asset_status' });
+    }
+}
+function accountAssetHeaders(signed) {
+    const headers = { accept: 'application/json', ...signed.headers };
+    const hasAuthorization = Object.keys(headers).some((key) => key.toLowerCase() === 'authorization');
+    const bodyNodeSecret = signed.bodyFields?.['node_secret'];
+    if (!hasAuthorization && typeof bodyNodeSecret === 'string' && bodyNodeSecret) {
+        headers['authorization'] = `Bearer ${bodyNodeSecret}`;
+    }
+    return headers;
+}
+async function parseCompatibilityResponse(response) {
+    if (!Number.isInteger(response.status) || response.status < 100 || response.status > 599) {
+        throw new HubUnreachableError('Private Hub account asset response has an invalid HTTP status', {
+            context: `GET ${PRIVATE_PUBLISHED_ASSETS_PATH}`,
+        });
+    }
+    try {
+        const parsed = await response.json();
+        const record = asRecord(parsed);
+        if (record)
+            return record;
+    }
+    catch {
+        // The normalized error below intentionally excludes response data.
+    }
+    throw new HubUnreachableError('Private Hub account asset response is not a JSON object', {
+        status: response.status,
+        context: `GET ${PRIVATE_PUBLISHED_ASSETS_PATH}`,
+    });
+}
+function parsePublishedPage(body, limit) {
+    const payload = asRecord(body['payload']) ?? body;
+    const assets = payload['assets'];
+    const hasMore = payload['has_more'] ?? payload['hasMore'];
+    const rawCursor = payload['next_cursor'] ?? payload['nextCursor'];
+    const count = payload['count'];
+    if (!Array.isArray(assets) || assets.length > limit || typeof hasMore !== 'boolean') {
+        throw malformedPublishedPage();
+    }
+    if (count !== undefined && (!Number.isSafeInteger(count) || count < 0)) {
+        throw malformedPublishedPage();
+    }
+    const nextCursor = rawCursor === null || rawCursor === undefined ? undefined : rawCursor;
+    if (nextCursor !== undefined && (typeof nextCursor !== 'string' || !nextCursor.trim() || nextCursor.length > PRIVATE_CURSOR_MAX_LENGTH)) {
+        throw malformedPublishedPage();
+    }
+    if (hasMore && nextCursor === undefined)
+        throw malformedPublishedPage();
+    return {
+        assets: assets,
+        ...(count !== undefined ? { count: count } : {}),
+        hasMore,
+        ...(nextCursor !== undefined ? { nextCursor } : {}),
+    };
+}
+function malformedPublishedPage() {
+    return new HubUnreachableError('Private Hub returned a malformed published asset page', {
+        context: `GET ${PRIVATE_PUBLISHED_ASSETS_PATH}`,
+    });
+}
+export function normalizePrivateHubBaseUrl(raw, env) {
+    const normalized = raw.trim().replace(/\/+$/, '');
+    assertPrivateCompatibilityUrlSecure(normalized, env);
+    const parsed = new URL(normalized);
+    if (parsed.username || parsed.password || normalized.includes('?') || normalized.includes('#')) {
+        throw new Error('Private Hub URL must not contain credentials, query parameters, or a fragment');
+    }
+    return parsed.href.replace(/[/]+$/, '');
+}
+function assertPrivateCompatibilityUrlSecure(url, env) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error('Private Hub URL is invalid');
+    }
+    if (parsed.protocol === 'https:')
+        return;
+    if (parsed.protocol === 'http:' && env['EVOLVER_PRIVATE_ALLOW_INSECURE'] === '1')
+        return;
+    throw new Error('Private Hub URL must use https');
+}
+const globalPrivateCompatibilityFetch = async (url, init) => {
+    const response = await fetch(url, {
+        method: init.method,
+        headers: init.headers,
+        ...(init.body ? { body: init.body } : {}),
+        redirect: 'error',
+    });
+    return { status: response.status, json: () => response.json() };
+};
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}

package/dist/private/adapterLoader.d.ts

@@ -1,5 +1,6 @@
 import { hub as hubNs } from '@evomap/evolver-core';
 import type { HelloResult, HeartbeatOptions, HeartbeatResult } from '../lifecycle/manager.js';
+import { type PrivateAccountAssetHub, type PrivateCompatibilityFetch } from './accountAssetCompatibility.js';
 export type PrivateHubWithLifecycle = hubNs.HubCapability & {
     hello(opts: {
         rotate: boolean;
@@ -7,6 +8,7 @@ export type PrivateHubWithLifecycle = hubNs.HubCapability & {
     }): Promise<HelloResult>;
     heartbeat(opts?: HeartbeatOptions): Promise<HeartbeatResult>;
 };
+export type PrivateProxyHub = PrivateHubWithLifecycle & PrivateAccountAssetHub;
 interface PrivateSsoExchange {
     identity: () => {
         subject: string;
@@ -29,11 +31,19 @@ export interface ConnectPrivateHubOptions {
     now?: () => number;
     /** One-shot invitation token (evoinv_…) — preferred over the SSO bearer for token_required hubs. */
     invitationToken?: string;
+    /** Ready credential from the standard Private Hub onboarding store. */
+    nodeSecret?: string;
+    fetchFn?: PrivateCompatibilityFetch;
 }
 type DynamicImporter = (specifier: string) => Promise<unknown>;
 export interface PrivateProxyHubRuntime {
-    hub: PrivateHubWithLifecycle;
+    hub: PrivateProxyHub;
     auth: hubNs.AuthProvider;
+    /** Enrollment-aware lifecycle entrypoint. Ready node_secret credentials must not re-run hello. */
+    hello(opts: {
+        rotate: boolean;
+        evolverVersion?: string;
+    }): Promise<HelloResult>;
 }
 export interface ConnectPrivateProxyHubOptions {
     hubUrl: string;
@@ -41,11 +51,21 @@ export interface ConnectPrivateProxyHubOptions {
     env: Record<string, string | undefined>;
     now?: () => number;
     importer?: DynamicImporter;
+    fetchFn?: PrivateCompatibilityFetch;
+    /** Durable credential minted by a previous invitation/SSO enrollment. */
+    storedNodeSecret?: string;
+    /** Persist a newly minted credential before the process can restart. */
+    onNodeSecretAdopted?: (nodeSecret: string) => void;
+    /** Fingerprint of the last successfully redeemed one-shot invitation. */
+    storedInvitationFingerprint?: string;
+    /** Persist the non-secret fingerprint after an invitation is redeemed. */
+    onInvitationRedeemed?: (fingerprint: string) => void;
 }
 export declare function resolvePrivateEnterpriseToken(env: Record<string, string | undefined>): string | undefined;
 /** One-shot invitation token (evoinv_…), matching the hub's official onboarding script (A2A_INVITATION_TOKEN).
  *  Preferred over the enterprise token for the default token_required enrollment mode. */
 export declare function resolvePrivateInvitationToken(env: Record<string, string | undefined>): string | undefined;
+export declare function resolvePrivateNodeSecret(env: Record<string, string | undefined>): string | undefined;
 export declare function resolvePrivateEnterpriseSubject(env: Record<string, string | undefined>): string;
 export declare function connectPrivateProxyHub(opts: ConnectPrivateProxyHubOptions): Promise<PrivateProxyHubRuntime>;
 export {};

package/dist/private/adapterLoader.js

@@ -1,4 +1,6 @@
 import { hub as hubNs } from '@evomap/evolver-core';
+import { createHash } from 'node:crypto';
+import { normalizePrivateHubBaseUrl, withPrivateAccountAssetCompatibility, } from './accountAssetCompatibility.js';
 const DEFAULT_PRIVATE_ADAPTER_MODULE = '@evomap/evolver-adapter-private';
 export function resolvePrivateEnterpriseToken(env) {
     return firstEnv(env, 'EVOMAP_ENTERPRISE_TOKEN', 'EVOMAP_PRIVATE_HUB_TOKEN', 'PHUB_ENTERPRISE_TOKEN', 'PRIVATE_HUB_ENTERPRISE_TOKEN');
@@ -8,36 +10,227 @@ export function resolvePrivateEnterpriseToken(env) {
 export function resolvePrivateInvitationToken(env) {
     return firstEnv(env, 'A2A_INVITATION_TOKEN');
 }
+export function resolvePrivateNodeSecret(env) {
+    return firstEnv(env, 'EVOMAP_NODE_SECRET', 'A2A_NODE_SECRET');
+}
 export function resolvePrivateEnterpriseSubject(env) {
     return firstEnv(env, 'EVOMAP_ENTERPRISE_SUBJECT', 'EVOMAP_PRIVATE_SUBJECT', 'PHUB_ENTERPRISE_SUBJECT', 'USER') ?? 'evolver-proxy';
 }
 export async function connectPrivateProxyHub(opts) {
     const invitationToken = resolvePrivateInvitationToken(opts.env);
+    const invitationFingerprint = invitationToken
+        ? createHash('sha256').update(invitationToken).digest('hex')
+        : undefined;
+    const usableInvitationToken = invitationFingerprint !== opts.storedInvitationFingerprint
+        ? invitationToken
+        : undefined;
     const token = resolvePrivateEnterpriseToken(opts.env);
-    if (!token && !invitationToken) {
-        throw new Error('EVOMAP_HUB_MODE=private 需要 A2A_INVITATION_TOKEN（推荐，对齐 PrivateHub onboarding）或 EVOMAP_ENTERPRISE_TOKEN（也兼容 EVOMAP_PRIVATE_HUB_TOKEN / PHUB_ENTERPRISE_TOKEN）');
+    const configuredNodeSecret = resolvePrivateNodeSecret(opts.env);
+    const nodeSecret = configuredNodeSecret ?? opts.storedNodeSecret?.trim();
+    if (nodeSecret && !isNodeSecret(nodeSecret)) {
+        throw new Error('Private Hub node_secret 必须是 64 位十六进制字符串');
+    }
+    if (!token && !usableInvitationToken && !nodeSecret) {
+        throw new Error('EVOMAP_HUB_MODE=private 需要 A2A_NODE_SECRET / EVOMAP_NODE_SECRET、A2A_INVITATION_TOKEN 或 EVOMAP_ENTERPRISE_TOKEN');
     }
+    const hubUrl = normalizePrivateHubBaseUrl(opts.hubUrl, opts.env);
     const moduleName = opts.env['EVOMAP_PRIVATE_ADAPTER_MODULE']?.trim() || DEFAULT_PRIVATE_ADAPTER_MODULE;
     const connectPrivateHub = await loadConnectPrivateHub(moduleName, opts.importer ?? ((specifier) => import(specifier)));
     const now = opts.now ?? (() => Date.now());
     const subject = resolvePrivateEnterpriseSubject(opts.env);
-    const { hub, auth } = connectPrivateHub({
-        hubUrl: opts.hubUrl,
+    const baseConnectionOptions = {
+        hubUrl,
         senderId: opts.senderId,
         env: opts.env,
         now,
         sso: {
             identity: () => ({ subject }),
-            exchange: async () => ({ token: token ?? '' }),
+            exchange: async () => ({ token: token ?? nodeSecret ?? '' }),
             now,
         },
-        ...(invitationToken ? { invitationToken } : {}),
+        ...(opts.fetchFn ? { fetchFn: opts.fetchFn } : {}),
+    };
+    const primaryInvitationToken = !nodeSecret && !configuredNodeSecret ? usableInvitationToken : undefined;
+    const { hub, auth } = connectPrivateHub({
+        ...baseConnectionOptions,
+        ...(nodeSecret ? { nodeSecret } : {}),
+        ...(primaryInvitationToken ? { invitationToken: primaryInvitationToken } : {}),
     });
     assertPrivateLifecycle(hub, moduleName);
+    const storedInvitationFallback = nodeSecret && !configuredNodeSecret && usableInvitationToken
+        ? connectPrivateHub({ ...baseConnectionOptions, invitationToken: usableInvitationToken })
+        : undefined;
+    const enterpriseFallback = primaryInvitationToken && token
+        ? connectPrivateHub(baseConnectionOptions)
+        : undefined;
+    if (storedInvitationFallback)
+        assertPrivateLifecycle(storedInvitationFallback.hub, moduleName);
+    if (enterpriseFallback)
+        assertPrivateLifecycle(enterpriseFallback.hub, moduleName);
+    if (nodeSecret)
+        await adoptReadyNodeSecret(auth, nodeSecret);
+    const primaryAdoptions = trackNodeSecretAdoptions(auth);
+    const storedInvitationAdoptions = storedInvitationFallback
+        ? trackNodeSecretAdoptions(storedInvitationFallback.auth)
+        : undefined;
+    const enterpriseAdoptions = enterpriseFallback
+        ? trackNodeSecretAdoptions(enterpriseFallback.auth)
+        : undefined;
     if (!hub.agentDirectory) {
         hub.agentDirectory = hubNs.unsupportedAgentDirectoryCapability('private_hub_agent_directory_not_supported');
     }
-    return { hub, auth };
+    const compatibleHub = withPrivateAccountAssetCompatibility(hub, {
+        baseUrl: hubUrl,
+        auth,
+        senderId: opts.senderId,
+        env: opts.env,
+        ...(opts.fetchFn ? { fetchFn: opts.fetchFn } : {}),
+    });
+    let readyHelloPending = Boolean(nodeSecret);
+    let invitationRedeemed = false;
+    let enterpriseFallbackSelected = false;
+    let helloInProgress = false;
+    const helloWithFallback = async (fallback, adoptions, helloOpts, rotate) => {
+        if (!adoptions?.available) {
+            throw new Error('private Hub adapter cannot report node_secret adoption');
+        }
+        if (rotate)
+            await fallback.auth.rotate();
+        const { result, adoptedNodeSecret } = await adoptions.capture(() => fallback.hub.hello(helloOpts));
+        if (!result.ok)
+            return result;
+        if (!adoptedNodeSecret)
+            throw new Error('private Hub fallback did not adopt a node_secret');
+        await adoptReadyNodeSecret(fallback.auth, adoptedNodeSecret);
+        await adoptReadyNodeSecret(auth, adoptedNodeSecret);
+        opts.onNodeSecretAdopted?.(adoptedNodeSecret);
+        return result;
+    };
+    const helloOnce = async (helloOpts) => {
+        if (enterpriseFallbackSelected || invitationRedeemed) {
+            if (!enterpriseFallback)
+                return { ok: false, error: 'private_invitation_reenrollment_required' };
+            return helloWithFallback(enterpriseFallback, enterpriseAdoptions, helloOpts, true);
+        }
+        if (primaryInvitationToken && !primaryAdoptions.available) {
+            throw new Error('private Hub adapter cannot report node_secret adoption');
+        }
+        let result;
+        let adoptedNodeSecret;
+        let usedAdapterHello = false;
+        if (nodeSecret && readyHelloPending) {
+            // A stored credential gets one ready probe before a fresh invitation takes over.
+            // Clear this before awaiting so a thrown probe cannot starve the fallback forever.
+            if (storedInvitationFallback)
+                readyHelloPending = false;
+            const tracked = await primaryAdoptions.capture(() => helloWithReadyPrivateCredential(compatibleHub, auth, nodeSecret, opts.senderId, helloOpts, primaryAdoptions.available));
+            readyHelloPending = false;
+            result = tracked.result;
+            adoptedNodeSecret = tracked.adoptedNodeSecret;
+            if (result.ok && !adoptedNodeSecret && !await authenticatesWithNodeSecret(auth, nodeSecret)) {
+                throw new Error('private Hub ready credential hello did not preserve an active node_secret');
+            }
+        }
+        else if (storedInvitationFallback) {
+            result = await helloWithFallback(storedInvitationFallback, storedInvitationAdoptions, helloOpts, false);
+            if (result.ok) {
+                invitationRedeemed = true;
+                if (invitationFingerprint)
+                    opts.onInvitationRedeemed?.(invitationFingerprint);
+            }
+            return result;
+        }
+        else {
+            usedAdapterHello = true;
+            const tracked = await primaryAdoptions.capture(() => compatibleHub.hello(helloOpts));
+            result = tracked.result;
+            adoptedNodeSecret = tracked.adoptedNodeSecret;
+        }
+        if (!result.ok && usedAdapterHello && primaryInvitationToken && enterpriseFallback) {
+            const fallbackResult = await helloWithFallback(enterpriseFallback, enterpriseAdoptions, helloOpts, true);
+            if (fallbackResult.ok)
+                enterpriseFallbackSelected = true;
+            return fallbackResult;
+        }
+        if (result.ok) {
+            if (adoptedNodeSecret && adoptedNodeSecret !== nodeSecret) {
+                await adoptReadyNodeSecret(auth, adoptedNodeSecret);
+                opts.onNodeSecretAdopted?.(adoptedNodeSecret);
+            }
+            if (usedAdapterHello && primaryInvitationToken) {
+                if (!adoptedNodeSecret) {
+                    throw new Error('private Hub enrollment did not adopt a node_secret');
+                }
+                invitationRedeemed = true;
+                if (invitationFingerprint)
+                    opts.onInvitationRedeemed?.(invitationFingerprint);
+            }
+        }
+        return result;
+    };
+    const hello = async (helloOpts) => {
+        if (helloInProgress)
+            throw new Error('concurrent private Hub hello is not supported');
+        helloInProgress = true;
+        try {
+            return await helloOnce(helloOpts);
+        }
+        finally {
+            helloInProgress = false;
+        }
+    };
+    return {
+        hub: compatibleHub,
+        auth,
+        hello,
+    };
+}
+const NODE_SECRET_ADOPTION_TRACKERS = new WeakMap();
+function trackNodeSecretAdoptions(auth) {
+    const existing = NODE_SECRET_ADOPTION_TRACKERS.get(auth);
+    if (existing)
+        return existing;
+    const candidate = auth;
+    const original = candidate.adoptNodeSecret;
+    let capturing = false;
+    let available = false;
+    let adoptedNodeSecret;
+    if (typeof original === 'function') {
+        const wrapped = function (nodeSecret) {
+            original.call(this, nodeSecret);
+            if (capturing)
+                adoptedNodeSecret = isNodeSecret(nodeSecret) ? nodeSecret : undefined;
+        };
+        try {
+            candidate.adoptNodeSecret = wrapped;
+            available = candidate.adoptNodeSecret === wrapped;
+        }
+        catch {
+            // A frozen adapter cannot expose reliable adoption provenance. Enrollment will fail closed below.
+        }
+    }
+    const tracker = {
+        get available() { return available; },
+        capture: async (operation) => {
+            if (capturing)
+                throw new Error('concurrent private Hub credential adoption is not supported');
+            capturing = true;
+            adoptedNodeSecret = undefined;
+            try {
+                const result = await operation();
+                return {
+                    result,
+                    ...(adoptedNodeSecret ? { adoptedNodeSecret } : {}),
+                };
+            }
+            finally {
+                capturing = false;
+                adoptedNodeSecret = undefined;
+            }
+        },
+    };
+    NODE_SECRET_ADOPTION_TRACKERS.set(auth, tracker);
+    return tracker;
 }
 async function loadConnectPrivateHub(moduleName, importer) {
     let loaded;
@@ -60,6 +253,48 @@ function assertPrivateLifecycle(hub, moduleName) {
         throw new Error(`${moduleName} 的 hub 缺少 hello/heartbeat lifecycle 方法，无法接入 evolver-proxy`);
     }
 }
+async function adoptReadyNodeSecret(auth, nodeSecret) {
+    const candidate = auth;
+    if (typeof candidate.adoptNodeSecret === 'function') {
+        candidate.adoptNodeSecret.call(auth, nodeSecret);
+    }
+    if (!await authenticatesWithNodeSecret(auth, nodeSecret)) {
+        throw new Error('private Hub adapter cannot activate the configured node_secret');
+    }
+}
+async function helloWithReadyPrivateCredential(hub, auth, nodeSecret, senderId, opts, canTrackAdoption = true) {
+    const nodeId = trimmedSenderId(senderId);
+    if (nodeId && await authenticatesWithNodeSecret(auth, nodeSecret))
+        return readyPrivateHello(nodeId);
+    if (!canTrackAdoption)
+        throw new Error('private Hub adapter cannot report node_secret adoption');
+    return await hub.hello(opts);
+}
+async function authenticatesWithNodeSecret(auth, nodeSecret) {
+    const signed = await auth.authenticate({ method: 'GET', path: '/a2a/assets/published-by-me' });
+    const authorization = headerValue(signed.headers, 'authorization');
+    const bodySecret = signed.bodyFields?.['node_secret'];
+    return authorization !== undefined
+        ? authorization === `Bearer ${nodeSecret}`
+        : bodySecret === nodeSecret;
+}
+function headerValue(headers, name) {
+    const lower = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === lower)
+            return value;
+    }
+    return undefined;
+}
+function trimmedSenderId(senderId) {
+    return senderId()?.trim() || undefined;
+}
+function readyPrivateHello(nodeId) {
+    return { ok: true, nodeId };
+}
+function isNodeSecret(value) {
+    return /^[a-f0-9]{64}$/i.test(value);
+}
 function firstEnv(env, ...keys) {
     for (const key of keys) {
         const value = env[key]?.trim();