@evomap/evolver-proxy 2.0.0-beta.0

package/README.md

@@ -0,0 +1,49 @@
+# @evomap/evolver-proxy
+
+The local proxy daemon: it relays LLM traffic and syncs the agent mailbox with an EvoMap hub.
+
+## Targeting a hub
+
+The proxy talks to a hub in one of two modes, selected by `EVOMAP_HUB_MODE`.
+
+### Public mode (default)
+
+```
+EVOMAP_HUB_URL=https://your-hub node packages/evolver-proxy/dist/bin/evolver-proxy.js
+```
+
+Public mode sends no private credential. It works against a public hub. Against a self-hosted
+**private** hub it can only complete the no-auth `/a2a/hello` handshake; every authenticated
+`/a2a/*` call (heartbeat, mailbox, publish) is rejected with `401 a2a_auth_required`.
+
+When an authenticated call fails the proxy now records an actionable hint in `sync:last_error` /
+`hub:auth_status` (surfaced in the daemon status snapshot), keyed off the hub error code so it does
+not misdirect:
+
+- `a2a_auth_required` (the hub demanded a credential the public adapter never sends) points at a
+  private hub, so the hint tells you to switch to private mode.
+- any other auth rejection (the node secret was sent but refused) points at a public-hub credential
+  problem, so the hint tells you to re-register the node.
+
+See issue #314.
+
+### Private mode (self-hosted / enterprise hub)
+
+Private mode authenticates every `/a2a/*` call with a bearer token, so it needs two things:
+
+1. An **enterprise token** via `EVOMAP_ENTERPRISE_TOKEN` (also accepts `EVOMAP_PRIVATE_HUB_TOKEN`
+   or `PHUB_ENTERPRISE_TOKEN`).
+2. The **private adapter** package `@evomap/evolver-adapter-private`. This ships in a separate
+   enterprise repo and is **not** vendored in this checkout. Install/link it, or point
+   `EVOMAP_PRIVATE_ADAPTER_MODULE` at a local build of a module that exports `connectPrivateHub`.
+
+```
+EVOMAP_HUB_MODE=private \
+EVOMAP_HUB_URL=http://127.0.0.1:4010 \
+EVOMAP_ENTERPRISE_TOKEN=<token> \
+EVOMAP_PRIVATE_ADAPTER_MODULE=/abs/path/to/adapter-private \
+node packages/evolver-proxy/dist/bin/evolver-proxy.js
+```
+
+Without the adapter, private mode fails fast at startup with a message naming the missing module.
+This checkout cannot target a private hub until that external adapter is available.

package/dist/bin/envFile.d.ts

@@ -0,0 +1,10 @@
+export interface EnvFileLoadResult {
+    loaded: boolean;
+    path?: string;
+    keys: string[];
+    error?: string;
+}
+export declare function expandHomePath(path: string): string;
+export declare function parseEnvFile(raw: string): Record<string, string>;
+export declare function loadEnvFile(path: string, env?: Record<string, string | undefined>): EnvFileLoadResult;
+export declare function loadEnvFileFromEnv(env?: Record<string, string | undefined>): EnvFileLoadResult;

package/dist/bin/envFile.js

@@ -0,0 +1,68 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+const ENV_FILE_KEY = 'EVOLVER_ENV_FILE';
+export function expandHomePath(path) {
+    if (path === '~')
+        return homedir();
+    if (path.startsWith('~/'))
+        return join(homedir(), path.slice(2));
+    return path;
+}
+export function parseEnvFile(raw) {
+    const out = {};
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const body = trimmed.startsWith('export ') ? trimmed.slice('export '.length).trimStart() : trimmed;
+        const eq = body.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = body.slice(0, eq).trim();
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            continue;
+        out[key] = unquoteEnvValue(body.slice(eq + 1).trim());
+    }
+    return out;
+}
+export function loadEnvFile(path, env = process.env) {
+    const resolved = isAbsolute(path) ? path : expandHomePath(path);
+    try {
+        const parsed = parseEnvFile(readFileSync(resolved, 'utf8'));
+        const keys = Object.keys(parsed);
+        for (const key of keys) {
+            if (key === ENV_FILE_KEY)
+                continue;
+            env[key] = parsed[key];
+        }
+        return { loaded: true, path: resolved, keys };
+    }
+    catch (err) {
+        return { loaded: false, path: resolved, keys: [], error: err instanceof Error ? err.message : String(err) };
+    }
+}
+export function loadEnvFileFromEnv(env = process.env) {
+    const path = env[ENV_FILE_KEY]?.trim();
+    if (!path)
+        return { loaded: false, keys: [] };
+    return loadEnvFile(path, env);
+}
+function unquoteEnvValue(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            const inner = value.slice(1, -1);
+            return first === '"' ? inner.replace(/\\(["\\nrt])/g, (_match, ch) => {
+                switch (ch) {
+                    case 'n': return '\n';
+                    case 'r': return '\r';
+                    case 't': return '\t';
+                    default: return ch;
+                }
+            }) : inner;
+        }
+    }
+    return value;
+}

package/dist/bin/evolver-llm-proxy.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function runLlmProxyCli(): void;

package/dist/bin/evolver-llm-proxy.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// Standalone LLM proxy entry: HTTP listen shell + tier router + trace capture. Deliberately independent of
+// the mailbox/hub daemon (bin/evolver-proxy.ts) — capturing LLM traces must not require a hub credential.
+//
+// Client wiring:   export ANTHROPIC_BASE_URL=http://127.0.0.1:<port>
+//                  export ANTHROPIC_AUTH_TOKEN=<token printed below>
+// Upstream creds:  ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN in THIS process's env (read per request).
+// Routing (opt-in):EVOMAP_ROUTER_ENABLED=1 + EVOMAP_MODEL_{CHEAP,MID,EXPENSIVE} (no IDs are ever hardcoded).
+// Trace material:  NDJSON under EVOLVER_LLM_TRACE_DIR (default $EVOLVER_HOME/proxy/traces or ~/.evomap/proxy/traces);
+//                  EVOLVER_LLM_TRACE=0 disables; legacy EVOMAP_PROXY_TRACE off values are also honored.
+// Hub analysis:    EVOLVER_LLM_TRACE_PROFILE_ANALYSIS=1 requires EVOLVER_LLM_TRACE_HUB_PUBLIC_KEY and writes
+//                  AES-GCM envelopes whose per-row DEK is RSA-OAEP-SHA256 wrapped for the Hub.
+import { randomBytes } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { daemon, events, mailbox } from '@evomap/evolver-core';
+import { buildMessagesHandler } from '../router/messagesRoute.js';
+import { buildProviderRoutes } from '../router/providerRoutes.js';
+import { makeAnthropicUpstream, makeGeminiUpstream, makeOllamaUpstream, makeOpenAIUpstream, makeVertexUpstream } from '../llm/upstream.js';
+import { JsonlTraceSink } from '../llm/traceSink.js';
+import { traceCollectionEnabled } from '../llm/traceConfig.js';
+import { LlmProxyServer } from '../llm/server.js';
+import { getCurrentVersion } from '../selfUpdate/version.js';
+import { resolveProxyStorePath } from './proxyStorePath.js';
+async function main(uninstallUnhandledRejectionGuard = () => undefined) {
+    const env = process.env;
+    const token = env['EVOLVER_LLM_TOKEN'] ?? randomBytes(24).toString('hex');
+    const traceEnabled = traceCollectionEnabled(env);
+    const traceDir = events.tracesDir();
+    let traceMailboxStore = null;
+    if (traceEnabled && env['EVOLVER_LLM_TRACE_MAILBOX'] !== '0') {
+        try {
+            const storePath = resolveProxyStorePath(env);
+            traceMailboxStore = new mailbox.MailboxStore({ path: storePath });
+        }
+        catch (err) {
+            process.stderr.write(`[evolver-llm-proxy] trace mailbox disabled: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    const sink = traceEnabled ? new JsonlTraceSink({
+        dir: traceDir,
+        producerVersion: getCurrentVersion(),
+        ...(traceMailboxStore ? { mailboxStore: traceMailboxStore } : {}),
+    }) : null;
+    const anthropicProxy = makeAnthropicUpstream();
+    const openAIProxy = makeOpenAIUpstream();
+    const geminiProxy = makeGeminiUpstream();
+    const ollamaProxy = makeOllamaUpstream();
+    const vertexProxy = makeVertexUpstream();
+    const handler = buildMessagesHandler({
+        anthropicProxy,
+        ...(sink ? { onTrace: sink.write } : {}),
+    });
+    const routes = buildProviderRoutes({
+        anthropicProxy,
+        openAIProxy,
+        geminiProxy,
+        ollamaProxy,
+        vertexProxy,
+        ...(sink ? { onTrace: sink.write } : {}),
+    });
+    const server = new LlmProxyServer({ handler, token, routes });
+    const { url } = await server.start();
+    process.stdout.write(`[evolver-llm-proxy] url=${url} token=${token} trace=${sink ? traceDir : 'off'}\n`);
+    let shuttingDown = false;
+    const shutdown = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        let exitCode = 0;
+        void server.stop()
+            .catch((err) => {
+            exitCode = 1;
+            process.stderr.write(`[evolver-llm-proxy] shutdown failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        })
+            .finally(() => {
+            try {
+                traceMailboxStore?.close();
+            }
+            catch (err) {
+                exitCode = 1;
+                process.stderr.write(`[evolver-llm-proxy] trace mailbox close failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+            uninstallUnhandledRejectionGuard();
+            process.exit(exitCode);
+        });
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+export function runLlmProxyCli() {
+    const uninstallUnhandledRejectionGuard = daemon.installUnhandledRejectionWindow();
+    main(uninstallUnhandledRejectionGuard).catch((e) => {
+        uninstallUnhandledRejectionGuard();
+        process.stderr.write(`[evolver-llm-proxy] fatal: ${e instanceof Error ? e.message : String(e)}\n`);
+        process.exit(1);
+    });
+}
+if (isDirectRun(import.meta.url, process.argv[1])) {
+    runLlmProxyCli();
+}
+function isDirectRun(metaUrl, argv1) {
+    if (!argv1)
+        return false;
+    try {
+        return realpathSync(fileURLToPath(metaUrl)) === realpathSync(argv1);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/bin/evolver-proxy.d.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { mailbox } from '@evomap/evolver-core';
+import { type SelfUpdatePolicy } from '../selfUpdate/policy.js';
+import { type ReleaseBinaryOptions } from '../selfUpdate/releaseBinary.js';
+import type { AtpProxyClient, ProxyDaemonDeps, ProxyTickReport } from '../daemon/proxyDaemon.js';
+import type { HelloLifecycleMode, HelloResult, HeartbeatOptions, HeartbeatResult } from '../lifecycle/manager.js';
+import type { InboundResult } from '../sync/engine.js';
+export declare function proxyUsage(): string;
+export declare function runProxyCli(): void;
+type PrivateAdapterImporter = (specifier: string) => Promise<unknown>;
+export interface RuntimeDeps {
+    mode: 'public' | 'private';
+    hubUrl: string;
+    senderId: () => string | undefined;
+    store: mailbox.MailboxStore;
+    env?: Record<string, string | undefined>;
+    now?: () => number;
+    privateImporter?: PrivateAdapterImporter;
+}
+export type PublicNodeSecretSource = 'env' | 'store' | 'hub_rotate' | 'legacy_file';
+export interface PublicNodeSecretSelection {
+    nodeSecret: string | undefined;
+    nodeSecretVersion?: number;
+    source: PublicNodeSecretSource;
+    storeSecret?: string;
+}
+export interface HubRuntime {
+    hub: ProxyDaemonDeps['hub'];
+    hello: (opts: {
+        rotate: boolean;
+        evolverVersion?: string;
+    }) => Promise<HelloResult>;
+    heartbeat: (opts?: HeartbeatOptions) => Promise<HeartbeatResult>;
+    helloMode?: HelloLifecycleMode;
+    atp?: AtpProxyClient;
+}
+interface ProxyLoopDaemon {
+    tick: () => Promise<ProxyTickReport>;
+    nextDelay: (last: InboundResult) => number;
+    sleep?: (delayMs: number) => Promise<void>;
+    setWakeHandler?: (wake: (() => void) | undefined) => void;
+}
+interface ProxyLoopLogger {
+    write: (chunk: string) => unknown;
+}
+export interface ProxyLoopOptions {
+    minDelayMs?: number;
+    errorDelayMs?: number;
+    maxIterations?: number;
+    sleep?: (delayMs: number) => Promise<void>;
+    logger?: ProxyLoopLogger;
+    /** 连续 tick throw 或 resolved fatal-candidate 达该值则抛错退出交 supervisor 重启; 默认 10; 瞬态成功会清零。 */
+    maxConsecutiveTickFailures?: number;
+}
+export declare function runProxyLoop(daemon: ProxyLoopDaemon, options?: ProxyLoopOptions): Promise<void>;
+interface CreateProxyDaemonDepsOptions {
+    runtime: HubRuntime;
+    store: mailbox.MailboxStore;
+    ipcToken: string;
+    ipcPort?: number;
+    evolverVersion: string;
+    selfUpdatePolicy: SelfUpdatePolicy;
+    env?: NodeJS.ProcessEnv;
+    selfUpdateOverrides?: ReleaseBinaryOptions & {
+        restart?: () => void;
+    };
+}
+export declare function createProxyDaemonDeps(options: CreateProxyDaemonDepsOptions): ProxyDaemonDeps;
+export declare function createSelfUpdateDeps(policy: SelfUpdatePolicy, currentVersion: string, env?: NodeJS.ProcessEnv, overrides?: ReleaseBinaryOptions & {
+    restart?: () => void;
+}): ProxyDaemonDeps['selfUpdate'];
+export declare function resolvePublicNodeSecret(deps: RuntimeDeps): PublicNodeSecretSelection;
+/**
+ * Hub rejected the cached node_secret as diverged (v1 a2aProtocol.js L1983-2017). Clear every
+ * durable copy — store keys + on-disk legacy files — so the next start re-acquires cleanly via an
+ * unauthenticated hello. The in-memory secret is already dropped by LegacyAuthShim before this runs.
+ */
+export declare function clearDivergedPublicNodeSecret(store: mailbox.MailboxStore, env?: NodeJS.ProcessEnv): void;
+export declare function persistSelectedPublicNodeSecret(store: mailbox.MailboxStore, selection: PublicNodeSecretSelection): void;
+export declare function persistPublicNodeSecretVersion(store: mailbox.MailboxStore, selection: PublicNodeSecretSelection, version: number | undefined): void;
+export declare function connectHubRuntime(deps: RuntimeDeps): Promise<HubRuntime>;
+export declare function resolveLegacyNodeSecret(envNodeSecret: string | undefined, storedNodeSecret: string | undefined, storedSource: string | undefined): string | undefined;
+export {};