@evomap/evolver-proxy 2.0.0-beta.18 → 2.0.0-beta.19

package/dist/daemon/systemdNotifier.js

@@ -0,0 +1,153 @@
+import { execFile } from 'node:child_process';
+const SYSTEMD_NOTIFY_TIMEOUT_MS = 5_000;
+const MIN_WATCHDOG_INTERVAL_MS = 1_000;
+const DEFAULT_READY_RETRY_DELAYS_MS = [250, 750];
+const MAX_READY_RETRIES = 4;
+const MAX_READY_RETRY_DELAY_MS = 5_000;
+const defaultSystemdNotifyExec = (command, args, options, callback) => {
+    execFile(command, [...args], options, (error) => { callback(error); });
+};
+export function systemdWatchdogIntervalMs(env = process.env) {
+    const usec = parsePositiveSafeInteger(env['WATCHDOG_USEC']);
+    if (usec === undefined)
+        return 0;
+    return Math.max(MIN_WATCHDOG_INTERVAL_MS, Math.floor(usec / 2_000));
+}
+export class SystemdNotifier {
+    options;
+    env;
+    platform;
+    now;
+    execFile;
+    readyRetryDelaysMs;
+    sleep;
+    timer;
+    readySent = false;
+    readyInFlight;
+    constructor(options) {
+        this.options = options;
+        this.env = options.env ?? process.env;
+        this.platform = options.platform ?? process.platform;
+        this.now = options.now ?? Date.now;
+        this.execFile = options.execFile ?? defaultSystemdNotifyExec;
+        this.readyRetryDelaysMs = normalizeReadyRetryDelays(options.readyRetryDelaysMs ?? DEFAULT_READY_RETRY_DELAYS_MS);
+        this.sleep = options.sleep ?? sleepMs;
+    }
+    async ready() {
+        if (!this.active())
+            return false;
+        if (this.readySent)
+            return true;
+        if (this.readyInFlight)
+            return this.readyInFlight;
+        const health = this.readHealth();
+        if (!health?.running || !health.ipcListening || !health.lifecycleArmed)
+            return false;
+        const attempt = this.announceReady();
+        this.readyInFlight = attempt;
+        void attempt.then(() => { if (this.readyInFlight === attempt)
+            this.readyInFlight = undefined; }, () => { if (this.readyInFlight === attempt)
+            this.readyInFlight = undefined; });
+        return attempt;
+    }
+    async readyOrThrow() {
+        if (!this.active())
+            return;
+        if (!await this.ready())
+            throw new Error('systemd_ready_notification_failed');
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    active() {
+        return this.platform === 'linux' && Boolean(this.env['NOTIFY_SOCKET']?.trim());
+    }
+    startWatchdog() {
+        if (this.timer)
+            return;
+        // The installed unit may run a stable recovery controller as MainPID and the
+        // proxy as its child. NotifyAccess=all intentionally authorizes that child.
+        const intervalMs = systemdWatchdogIntervalMs(this.env);
+        if (intervalMs === 0)
+            return;
+        this.timer = setInterval(() => { this.pingWatchdog(intervalMs); }, intervalMs);
+        this.timer.unref?.();
+    }
+    pingWatchdog(freshnessMs) {
+        const health = this.readHealth();
+        if (!health?.running || !health.ipcListening || !health.lifecycleArmed)
+            return;
+        if (health.consecutiveFailures !== 0 || health.lastTickAt === undefined)
+            return;
+        const ageMs = this.now() - health.lastTickAt;
+        const plannedSleepHealthy = health.nextTickDueAt !== undefined
+            && this.now() <= health.nextTickDueAt + freshnessMs;
+        if (!Number.isFinite(ageMs) || ageMs < 0 || (ageMs > freshnessMs && !plannedSleepHealthy))
+            return;
+        void this.notify('WATCHDOG=1');
+    }
+    async announceReady() {
+        const attempts = this.readyRetryDelaysMs.length + 1;
+        for (let attempt = 0; attempt < attempts; attempt += 1) {
+            const health = this.readHealth();
+            if (!health?.running || !health.ipcListening || !health.lifecycleArmed)
+                return false;
+            if (await this.notify('READY=1')) {
+                this.readySent = true;
+                this.startWatchdog();
+                return true;
+            }
+            const delayMs = this.readyRetryDelaysMs[attempt];
+            if (delayMs !== undefined) {
+                try {
+                    await this.sleep(delayMs);
+                }
+                catch {
+                    return false;
+                }
+            }
+        }
+        return false;
+    }
+    readHealth() {
+        try {
+            return this.options.health();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    notify(state) {
+        return new Promise((resolve) => {
+            try {
+                this.execFile('systemd-notify', [state], {
+                    env: this.env,
+                    timeout: SYSTEMD_NOTIFY_TIMEOUT_MS,
+                    windowsHide: true,
+                }, (error) => { resolve(error === null); });
+            }
+            catch {
+                // Keep delivery failures as data: READY is enforced by readyOrThrow(), while watchdog pings stay best-effort.
+                resolve(false);
+            }
+        });
+    }
+}
+function normalizeReadyRetryDelays(values) {
+    return values.slice(0, MAX_READY_RETRIES).map((value) => (Number.isFinite(value)
+        ? Math.min(MAX_READY_RETRY_DELAY_MS, Math.max(0, Math.floor(value)))
+        : 0));
+}
+function sleepMs(delayMs) {
+    return new Promise((resolve) => { setTimeout(resolve, delayMs); });
+}
+function parsePositiveSafeInteger(value) {
+    const trimmed = value?.trim();
+    if (!trimmed || !/^\d+$/.test(trimmed))
+        return undefined;
+    const parsed = Number(trimmed);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 export declare const PACKAGE = "@evomap/evolver-proxy";
 export * from './sync/engine.js';
 export * from './lifecycle/manager.js';
+export * from './lifecycle/claimNudge.js';
 export * from './daemon/proxyDaemon.js';
+export * from './daemon/publishRecallVerifier.js';
 export * from './lifecycle/deployGuard.js';
 export * from './router/index.js';
 export * from './llm/index.js';

package/dist/index.js

@@ -1,7 +1,9 @@
 export const PACKAGE = '@evomap/evolver-proxy';
 export * from './sync/engine.js';
 export * from './lifecycle/manager.js';
+export * from './lifecycle/claimNudge.js';
 export * from './daemon/proxyDaemon.js';
+export * from './daemon/publishRecallVerifier.js';
 export * from './lifecycle/deployGuard.js';
 export * from './router/index.js';
 export * from './llm/index.js';

package/dist/lifecycle/claimNudge.d.ts

@@ -0,0 +1,20 @@
+export interface ClaimNudgeHelloResult {
+    ok: boolean;
+    claimCode?: string;
+    claimUrl?: string;
+}
+export interface ClaimNudgeStateStore {
+    getState(key: string): string | undefined;
+    setState(key: string, value: string): void;
+}
+export interface ClaimNudgeOptions {
+    store: ClaimNudgeStateStore;
+    hubUrl: string;
+    env?: Readonly<Record<string, string | undefined>>;
+    now?: () => number;
+    write?: (text: string) => void;
+}
+export type ClaimNudge = (result: ClaimNudgeHelloResult) => boolean;
+export declare function createClaimNudge(options: ClaimNudgeOptions): ClaimNudge;
+export declare function wrapHelloWithClaimNudge<T extends ClaimNudgeHelloResult, O>(hello: (options: O) => Promise<T>, nudge: ClaimNudge): (options: O) => Promise<T>;
+export declare function claimNudgeCooldownMs(raw: string | undefined): number;

package/dist/lifecycle/claimNudge.js

@@ -0,0 +1,124 @@
+const DEFAULT_COOLDOWN_MS = 6 * 60 * 60_000;
+const MIN_COOLDOWN_MS = 60_000;
+const MAX_COOLDOWN_MS = 30 * 24 * 60 * 60_000;
+const MAX_STATE_ENTRIES = 32;
+const STATE_KEY = 'lifecycle:claim_nudge:v1';
+const CLAIM_CODE_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{1,127}$/;
+export function createClaimNudge(options) {
+    const env = options.env ?? process.env;
+    const now = options.now ?? (() => Date.now());
+    const write = options.write ?? ((text) => { process.stderr.write(text); });
+    let memory = { version: 1, entries: {} };
+    return (result) => {
+        if (!result.ok || env['EVOLVER_DISABLE_CLAIM_NUDGE'] === '1')
+            return false;
+        const code = normalizeClaimCode(result.claimCode);
+        const url = code ? trustedClaimUrl(result.claimUrl, options.hubUrl) : undefined;
+        if (!code || !url)
+            return false;
+        const at = now();
+        const cooldownMs = claimNudgeCooldownMs(env['EVOLVER_CLAIM_NUDGE_COOLDOWN_MS']);
+        const state = mergeState(readState(options.store), memory);
+        const lastPrintedAt = state.entries[code] ?? 0;
+        if (lastPrintedAt > 0 && at - lastPrintedAt < cooldownMs)
+            return false;
+        const message = [
+            '',
+            '[evolver-proxy] This node is not linked to an EvoMap web account.',
+            `Claim URL: ${url}`,
+            `Claim code: ${code}`,
+            'Claiming is optional; the proxy continues to run without it.',
+            '',
+        ].join('\n');
+        try {
+            write(message);
+        }
+        catch {
+            return false;
+        }
+        memory = pruneState({ ...state.entries, [code]: at });
+        try {
+            options.store.setState(STATE_KEY, JSON.stringify(memory));
+        }
+        catch { /* memory still suppresses repeats */ }
+        return true;
+    };
+}
+export function wrapHelloWithClaimNudge(hello, nudge) {
+    return async (options) => {
+        const result = await hello(options);
+        try {
+            nudge(result);
+        }
+        catch { /* a terminal nudge must never break hello */ }
+        return result;
+    };
+}
+export function claimNudgeCooldownMs(raw) {
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return DEFAULT_COOLDOWN_MS;
+    return Math.max(MIN_COOLDOWN_MS, Math.min(Math.floor(parsed), MAX_COOLDOWN_MS));
+}
+function normalizeClaimCode(value) {
+    const code = value?.trim();
+    return code && CLAIM_CODE_RE.test(code) ? code : undefined;
+}
+function trustedClaimUrl(value, hubUrl) {
+    const raw = value?.trim();
+    if (!raw || raw.length > 2_048)
+        return undefined;
+    try {
+        const url = new URL(raw);
+        const hub = new URL(hubUrl);
+        if (url.username || url.password)
+            return undefined;
+        const sameOrigin = url.origin === hub.origin;
+        const evomapHost = url.hostname === 'evomap.ai' || url.hostname.endsWith('.evomap.ai');
+        if (url.protocol === 'https:' && (sameOrigin || evomapHost))
+            return url.toString();
+        if (url.protocol === 'http:' && sameOrigin && isLoopback(url.hostname))
+            return url.toString();
+    }
+    catch {
+        // Invalid or non-absolute URLs are never printed.
+    }
+    return undefined;
+}
+function isLoopback(hostname) {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+}
+function readState(store) {
+    try {
+        const raw = store.getState(STATE_KEY);
+        if (!raw)
+            return { version: 1, entries: {} };
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1 || !parsed.entries || typeof parsed.entries !== 'object' || Array.isArray(parsed.entries)) {
+            return { version: 1, entries: {} };
+        }
+        const entries = {};
+        for (const [code, value] of Object.entries(parsed.entries)) {
+            if (CLAIM_CODE_RE.test(code) && typeof value === 'number' && Number.isFinite(value) && value > 0)
+                entries[code] = value;
+        }
+        return { version: 1, entries };
+    }
+    catch {
+        return { version: 1, entries: {} };
+    }
+}
+function mergeState(a, b) {
+    const entries = { ...a.entries };
+    for (const [code, at] of Object.entries(b.entries))
+        entries[code] = Math.max(entries[code] ?? 0, at);
+    return { version: 1, entries };
+}
+function pruneState(entries) {
+    return {
+        version: 1,
+        entries: Object.fromEntries(Object.entries(entries)
+            .sort((left, right) => right[1] - left[1])
+            .slice(0, MAX_STATE_ENTRIES)),
+    };
+}

package/dist/lifecycle/manager.d.ts

@@ -18,6 +18,8 @@ export interface HelloResult {
     ok: boolean;
     authError?: boolean;
     nodeId?: string;
+    claimCode?: string;
+    claimUrl?: string;
     rateLimitUntilMs?: number;
     error?: string;
     details?: unknown;
@@ -40,6 +42,7 @@ export interface HeartbeatResult {
     httpStatus?: number;
     lastUpdateAck?: LastUpdateAck;
     forceUpdate?: ForceUpdateDirective;
+    capabilityGaps?: readonly string[];
 }
 export interface HeartbeatTickResult {
     ok: boolean;
@@ -98,6 +101,7 @@ export declare class LifecycleManager {
     private recordHubUnreachable;
     private clearLegacyNodeSecretVersion;
     private verifyReauthHeartbeat;
+    private persistCapabilityGaps;
     private heartbeatOptions;
     private callHello;
     private handleLastUpdateAck;

package/dist/lifecycle/manager.js

@@ -1,4 +1,4 @@
-import { mailbox, hub as hubNs } from '@evomap/evolver-core';
+import { mailbox, hub as hubNs, signals } from '@evomap/evolver-core';
 import { clearLastUpdateOnAck, isLastUpdateRelatedError, readPendingLastUpdate, shouldClearForLastUpdateAck, } from '../selfUpdate/lastUpdate.js';
 export const DEFAULT_HEARTBEAT_INTERVAL_MS = 360_000;
 export const MIN_HEARTBEAT_INTERVAL_MS = 30_000;
@@ -125,6 +125,7 @@ export class LifecycleManager {
             this.handleLastUpdateAck(res, sentLastUpdate, now);
             this.maybeTriggerForceUpdate(res);
             if (res.ok) {
+                this.persistCapabilityGaps(res.capabilityGaps, now);
                 this.deps.store.setState(K.hubUnreachableUntil, '0');
                 this.deps.store.setState(K.authStatus, 'ok');
                 this.deps.store.setState(K.lastError, '');
@@ -293,8 +294,10 @@ export class LifecycleManager {
             const hb = await this.deps.heartbeat(opts);
             this.handleLastUpdateAck(hb, opts?.lastUpdate, now);
             this.maybeTriggerForceUpdate(hb);
-            if (hb.ok)
+            if (hb.ok) {
+                this.persistCapabilityGaps(hb.capabilityGaps, now);
                 return 'ok';
+            }
             if (isHubUnreachableResult(hb)) {
                 this.recordHubUnreachable(hb, now);
                 return 'hub_unreachable';
@@ -309,6 +312,16 @@ export class LifecycleManager {
             throw err;
         }
     }
+    persistCapabilityGaps(capabilityGaps, observedAt) {
+        if (capabilityGaps === undefined)
+            return;
+        try {
+            this.deps.store.setState(signals.CAPABILITY_GAPS_STATE_KEY, signals.serializeCapabilityGapsState(capabilityGaps, observedAt));
+        }
+        catch {
+            // Curriculum is advisory; a failed optional KV write must not turn a healthy heartbeat into a failure.
+        }
+    }
     heartbeatOptions() {
         const opts = {};
         if (this.deps.evolverVersion)

package/dist/llm/upstream.d.ts

@@ -49,6 +49,9 @@ export interface BedrockRuntimeFactory {
     createInvokeModelCommand(input: BedrockInvokeInput): unknown;
     createInvokeModelWithResponseStreamCommand(input: BedrockInvokeInput): unknown;
 }
+declare function warnDeprecatedOpenAICompatible(env: NodeJS.ProcessEnv): void;
+/** Test helper: reset once-warn latch (unit tests only). */
+declare function resetDeprecatedOpenAICompatibleWarning(): void;
 export declare function resolveOpenAIUpstreamUrl(env?: NodeJS.ProcessEnv): string;
 /** Resolve the upstream base URL. OpenAI-compatible routes never inherit the Anthropic-wide override. */
 export declare function resolveUpstreamUrl(env?: NodeJS.ProcessEnv, upstreamMode?: string): string;
@@ -65,4 +68,5 @@ export declare function makeAnthropicUpstream(opts?: AnthropicUpstreamOptions):
 export declare function makeOpenAIUpstream(opts?: ProviderUpstreamOptions): AnthropicProxy;
 export declare function makeGeminiUpstream(opts?: ProviderUpstreamOptions): AnthropicProxy;
 export declare function makeOllamaUpstream(opts?: ProviderUpstreamOptions): AnthropicProxy;
-export declare function makeVertexUpstream(opts?: ProviderUpstreamOptions): AnthropicProxy;
+export declare function makeVertexUpstream(opts?: ProviderUpstreamOptions): AnthropicProxy;
+export { warnDeprecatedOpenAICompatible, resetDeprecatedOpenAICompatibleWarning };

package/dist/llm/upstream.js

@@ -32,6 +32,27 @@ 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 warnDeprecatedOpenAICompatible(env) {
+    const deprecatedValue = env['EVOMAP_OPENAI_COMPATIBLE_BASE_URLS'] || env['EVOLVER_OPENAI_COMPATIBLE_BASE_URLS'];
+    if (!deprecatedValue || warnedDeprecatedOpenAICompatible)
+        return;
+    warnedDeprecatedOpenAICompatible = true;
+    console.warn('[proxy] DEPRECATED: EVOMAP_OPENAI_COMPATIBLE_BASE_URLS / EVOLVER_OPENAI_COMPATIBLE_BASE_URLS is ignored for routing. ' +
+        'V2 accepts only https://*.api.openai.com/v1 via EVOLVER_LLM_OPENAI_BASE_URL, EVOMAP_OPENAI_BASE_URL, or OPENAI_BASE_URL. ' +
+        'LiteLLM / OpenRouter / Azure OpenAI-compatible hosts are not accepted on this OpenAI path — use a reverse proxy in front of api.openai.com or a non-OpenAI provider mode. ' +
+        'Remove the deprecated multi-base env var.');
+}
+/** 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');
@@ -57,6 +78,7 @@ function normalizeOpenAIBaseUrl(raw) {
     return value;
 }
 export function resolveOpenAIUpstreamUrl(env = process.env) {
+    warnDeprecatedOpenAICompatible(env);
     return normalizeOpenAIBaseUrl(env['EVOLVER_LLM_OPENAI_BASE_URL'] || env['EVOMAP_OPENAI_BASE_URL'] || env['OPENAI_BASE_URL'] || DEFAULT_OPENAI_UPSTREAM_URL);
 }
 function pathForOpenAIBase(path) {
@@ -488,4 +510,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/sync/engine.d.ts

@@ -23,6 +23,13 @@ export interface SyncEngineDeps {
     onOutboundSucceeded?: (envelope: Envelope, result: unknown) => void | Promise<void>;
     /** Cache a durable facade terminal result after SyncEngine moved the envelope to DLQ. */
     onOutboundTerminal?: (envelope: Envelope, error: unknown) => void | Promise<void>;
+    /** Return the durable marker that proves a racing facade request already reached external acceptance. */
+    acceptedOutcomeKey?: (envelope: Envelope) => string | undefined;
+    /** Return a replayable terminal result that must be committed atomically with the mailbox DLQ transition. */
+    terminalOutcome?: (envelope: Envelope, error: unknown) => {
+        key: string;
+        result: unknown;
+    } | undefined;
     /** Canonicalize an inbound envelope before durable insertion. */
     normalizeInboundEnvelope?: (envelope: Envelope) => Envelope;
     onOutboundFlushed?: (result: OutboundResult) => void | Promise<void>;
@@ -44,6 +51,7 @@ export interface InboundResult {
 }
 export declare class SyncEngine {
     private readonly deps;
+    private readonly acceptedTaskOutboundMemory;
     private lastActivityAt;
     constructor(deps: SyncEngineDeps);
     /** 出站: claim proxy 消息 → 经 proxyHandler 推 hub → complete; 终态(publish reject)直进 DLQ 不重试(money-safety). */
@@ -59,6 +67,10 @@ export declare class SyncEngine {
     private notifyOutboundFlushed;
     private normalizeOutbound;
     private outboundDedupKey;
+    private acceptedTaskOutbound;
+    private durableAcceptedTaskOutbound;
+    private completeAcceptedOutcome;
+    private rememberAcceptedTaskOutbound;
     private safeAck;
     /** AgentEvent → core Envelope; 未知类型(不在目录)跳过. */
     private toEnvelope;