pi-harness-runtime 1.1.387 → 1.1.388

package/packages/knowledge-graph/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/knowledge-graph",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Knowledge Graph extraction and provenance linking for SKILL.md files",
   "type": "module",
   "main": "./dist/index.js",

package/packages/knowledge-retrieval/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/knowledge-retrieval",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Knowledge retrieval via TencentDB-Agent-Memory MCP (RFC-0105)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/laravel-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/laravel-plugin",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Laravel framework analysis — artisan commands, Eloquent models, Blade",
   "type": "module",
   "main": "./dist/index.js",

package/packages/learning-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/learning-engine",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Learning engine for extracting lessons from runtime execution (RFC-0058)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/mcp-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/mcp-adapter",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "type": "module",
   "description": "MCP server adapter for pi-harness — exposes harness capabilities as MCP tools/resources/prompts (RFC-0068)",
   "main": "dist/index.js",

package/packages/memory-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/memory-engine",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Memory engine with OKF integration for durable knowledge management (RFC-0060)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/milestone-manager/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/milestone-manager",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Track milestones and alerts when items are at risk",
   "type": "module",
   "main": "./dist/index.js",

package/packages/model-registry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/model-registry",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Model Registry for pi-harness-runtime — centralized model metadata with pricing",
   "type": "module",
   "main": "./dist/index.js",

package/packages/nextjs-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/nextjs-plugin",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Next.js framework detection and analysis for pi-harness-runtime (RFC-0062)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/notification/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/notification",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "pi-harness-runtime — notification",
   "type": "module",
   "main": "./dist/index.js",

package/packages/observability/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/observability",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Comprehensive observability system with structured logging, tracing, metrics, and alerting",
   "type": "module",
   "main": "./dist/index.js",

package/packages/okf-indexer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/okf-indexer",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "OKF document indexer for SKILL.md files (RFC-0106)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/paperclip-integration/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/paperclip-integration",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Paperclip API integration: poll agent inbox, route tasks to pi.dev, Telegram alerts",
   "type": "module",
   "main": "./dist/index.js",

package/packages/performance-optimizer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/performance-optimizer",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Performance optimization analyzer for pi-harness runtime (RFC-0056)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/permission-mode/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/permission-mode",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "type": "module",
   "description": "Runtime permission modes for pi-harness - Supervised/Auto/Full-access",
   "main": "./dist/index.js",

package/packages/privilege-broker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/privilege-broker",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Privilege Broker — capability registry and command executor for autonomous runtime (RFC-0101 §7)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/project-analyzer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/project-analyzer",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Project analysis system for pi-harness-runtime - detects frameworks, rules, and project structure",
   "type": "module",
   "main": "./dist/index.js",

package/packages/project-bootstrap/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/project-bootstrap",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Project scaffolding from typed ProjectSpec",
   "type": "module",
   "main": "./dist/index.js",

package/packages/projection-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/projection-engine",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/prompt-compiler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/prompt-compiler",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Deterministic prompt compiler for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/prompt-versioning/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/prompt-versioning",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "type": "module",
   "description": "Version control for prompts with rollback support (RFC-0019)",
   "main": "dist/index.js",

package/packages/provider-adapter-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/provider-adapter-sdk",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "SDK for building, testing, and registering AI provider adapters",
   "type": "module",
   "main": "./dist/index.js",

package/packages/provider-router/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/provider-router",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Enhanced Provider Router for pi-harness-runtime — intelligent routing with capabilities, costs, and quotas",
   "type": "module",
   "main": "./dist/provider-router.js",

package/packages/provider-selector/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/provider-selector",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Multi-Provider Selector — route requests by cost, quality, and latency (RFC-0012)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/providers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/providers",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "pi-harness-runtime — providers",
   "type": "module",
   "main": "./dist/index.js",

package/packages/qdrant-skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/qdrant-skills",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "Qdrant vector search integration for Hermes-style skill system",
   "type": "module",
   "main": "./dist/index.js",

package/packages/quota-manager/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/quota-manager",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "pi-harness-runtime — quota-manager",
   "type": "module",
   "main": "./dist/index.js",

package/packages/rate-limiter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/rate-limiter",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "type": "module",
   "description": "Rate limiting with token bucket algorithm (RFC-0023)",
   "main": "dist/index.js",

package/packages/react-vite-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/react-vite-plugin",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "description": "React/Vite framework analysis — components, config, TypeScript setup",
   "type": "module",
   "main": "./dist/index.js",

package/packages/relay/dist/index.d.ts

@@ -12,5 +12,8 @@ export { RelayServer, createRelayServer } from './server.js';
 export type { RelayServerOptions } from './server.js';
 export { RelayClient } from './client.js';
 export type { RelayClientCallbacks } from './client.js';
+export { resolveRelayEndpoint, deriveRelayWsUrl, isRelayWsUrl, describeRelayEndpoint, } from './relay-endpoint.js';
+export type { RelayEndpointEnv, RelayEndpointResolution, ResolveRelayEndpointOptions, } from './relay-endpoint.js';
+export { RELAY_URL_SOURCES, RELAY_TOKEN_SOURCES, } from './relay-endpoint.js';
 export { PROTOCOL_VERSION, generateMessageId, createTimestamp, } from './types.js';
 export type { RelayConfig, RelayTunnel, ConnectionState, ConnectionStateChange, BaseMessage, SnapshotMessage, SynchronizedMessage, CallbackPayload, CallbackMessage, StatusKind, StatusMessage, PingMessage, PongMessage, AuthRequestMessage, AuthResponseMessage, SubscribeMessage, ConnectedMessage, ServerMessage, ClientMessage, RelayMessage, } from './types.js';

package/packages/relay/dist/index.js

@@ -12,5 +12,8 @@
 export { RelayServer, createRelayServer } from './server.js';
 // Client
 export { RelayClient } from './client.js';
+// Endpoint resolution (relay URL + auth token discovery)
+export { resolveRelayEndpoint, deriveRelayWsUrl, isRelayWsUrl, describeRelayEndpoint, } from './relay-endpoint.js';
+export { RELAY_URL_SOURCES, RELAY_TOKEN_SOURCES, } from './relay-endpoint.js';
 // Types
 export { PROTOCOL_VERSION, generateMessageId, createTimestamp, } from './types.js';

package/packages/relay/dist/relay-endpoint.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Relay endpoint resolution.
+ *
+ * Resolves the relay WebSocket URL and the auth token from the SAME sources
+ * the relay server uses (see scripts/unified-webhook-server.ts), so a client
+ * and the server always agree:
+ *
+ *   URL:   RELAY_WS_URL env -> keys/relay-ws-url.txt -> derived from keys/telegram-webhook-url.txt
+ *   Token: RELAY_AUTH_TOKEN env -> keys/relay-auth-token.txt -> keys/telegram-webhook-secret.txt
+ *
+ * The token value is never logged: only the NAME of the source it came from.
+ */
+/** Environment variables consulted by the resolver. */
+export interface RelayEndpointEnv {
+    RELAY_WS_URL?: string;
+    RELAY_AUTH_TOKEN?: string;
+}
+/** Result of a relay endpoint resolution. */
+export interface RelayEndpointResolution {
+    /** WebSocket URL, or null when it could not be resolved. */
+    url: string | null;
+    /** Where the URL came from (e.g. "env RELAY_WS_URL"). Never contains a secret. */
+    urlSource: string | null;
+    /** Auth token, or null when it could not be resolved. */
+    token: string | null;
+    /** Where the token came from (e.g. "keys/telegram-webhook-secret.txt"). Never contains the token. */
+    tokenSource: string | null;
+    /** Human readable description of what is missing (never contains a token). */
+    missing: string[];
+    /** Human readable caveats about the resolved endpoint (never contains a token). */
+    notes: string[];
+}
+/** Options for {@link resolveRelayEndpoint}. */
+export interface ResolveRelayEndpointOptions {
+    /** Environment to read (defaults to process.env). */
+    env?: RelayEndpointEnv;
+    /** Directory holding the key files (e.g. ~/.pi-harness-runtime/keys). */
+    keysDir: string;
+    /** Optional file reader override (used by the tests). */
+    readFile?: (path: string) => string | undefined;
+}
+/** Source names, in the order they are consulted. */
+export declare const RELAY_URL_SOURCES: readonly ["env RELAY_WS_URL", "keys/relay-ws-url.txt", "keys/telegram-webhook-url.txt (derived)"];
+export declare const RELAY_TOKEN_SOURCES: readonly ["env RELAY_AUTH_TOKEN", "keys/relay-auth-token.txt", "keys/telegram-webhook-secret.txt"];
+/**
+ * The token sources are the SAME chain the relay server uses, so the client
+ * and the server can never disagree about the credential.
+ *
+ * Note: `keys/telegram-webhook-secret.txt` is also the secret the Telegram
+ * webhook expects in its `x-telegram-bot-api-secret-token` header. Sharing it
+ * with the WebSocket relay widens the blast radius of that secret - put a
+ * dedicated token in `keys/relay-auth-token.txt` (it is preferred) when the
+ * relay and the webhook do not have to share one.
+ *
+ * The Telegram webhook secret itself may also come from the environment
+ * variable TELEGRAM_WEBHOOK_SECRET; that variable belongs to the HTTP
+ * webhook, not to the relay, and is therefore not part of this chain.
+ */
+/**
+ * Derive the relay WebSocket URL from the Telegram webhook URL.
+ *
+ * The derivation keeps the host (and port) of the webhook URL and replaces the
+ * path with /ws, because the relay is exposed on the same origin as the
+ * webhook:
+ *
+ *   https://webhook.bunchee.online/telegram -> wss://webhook.bunchee.online/ws
+ *
+ * That only works when the origin serves /ws, i.e. behind the reverse proxy
+ * that maps /ws to the relay port (nginx: location /ws -> 127.0.0.1:8444).
+ * When the webhook URL addresses the application DIRECTLY, the relay listens
+ * on WS_PORT (default 8444), not on the HTTP port - use RELAY_WS_URL or
+ * keys/relay-ws-url.txt for that setup.
+ */
+export declare function deriveRelayWsUrl(webhookUrl: string): string | null;
+/**
+ * True when the value looks like a WebSocket URL.
+ *
+ * Credentials ("wss://user:pass@host") and query strings are rejected: the
+ * resolved URL is written to the log, and neither belongs there.
+ */
+export declare function isRelayWsUrl(value: string): boolean;
+/**
+ * Resolve the relay WebSocket URL and auth token.
+ *
+ * The first non-empty source wins. A blank file counts as missing (an empty
+ * value is a configuration mistake, not a valid endpoint). A source that holds
+ * a value which was REJECTED is reported in `missing` so the operator can see
+ * why the resolver moved on.
+ */
+export declare function resolveRelayEndpoint(options: ResolveRelayEndpointOptions): RelayEndpointResolution;
+/**
+ * Log-safe description of a resolution (contains no token value).
+ */
+export declare function describeRelayEndpoint(resolution: RelayEndpointResolution): string;

package/packages/relay/dist/relay-endpoint.js

@@ -0,0 +1,239 @@
+/**
+ * Relay endpoint resolution.
+ *
+ * Resolves the relay WebSocket URL and the auth token from the SAME sources
+ * the relay server uses (see scripts/unified-webhook-server.ts), so a client
+ * and the server always agree:
+ *
+ *   URL:   RELAY_WS_URL env -> keys/relay-ws-url.txt -> derived from keys/telegram-webhook-url.txt
+ *   Token: RELAY_AUTH_TOKEN env -> keys/relay-auth-token.txt -> keys/telegram-webhook-secret.txt
+ *
+ * The token value is never logged: only the NAME of the source it came from.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Source names, in the order they are consulted. */
+export const RELAY_URL_SOURCES = [
+    "env RELAY_WS_URL",
+    "keys/relay-ws-url.txt",
+    "keys/telegram-webhook-url.txt (derived)",
+];
+export const RELAY_TOKEN_SOURCES = [
+    "env RELAY_AUTH_TOKEN",
+    "keys/relay-auth-token.txt",
+    "keys/telegram-webhook-secret.txt",
+];
+/**
+ * The token sources are the SAME chain the relay server uses, so the client
+ * and the server can never disagree about the credential.
+ *
+ * Note: `keys/telegram-webhook-secret.txt` is also the secret the Telegram
+ * webhook expects in its `x-telegram-bot-api-secret-token` header. Sharing it
+ * with the WebSocket relay widens the blast radius of that secret - put a
+ * dedicated token in `keys/relay-auth-token.txt` (it is preferred) when the
+ * relay and the webhook do not have to share one.
+ *
+ * The Telegram webhook secret itself may also come from the environment
+ * variable TELEGRAM_WEBHOOK_SECRET; that variable belongs to the HTTP
+ * webhook, not to the relay, and is therefore not part of this chain.
+ */
+/**
+ * Derive the relay WebSocket URL from the Telegram webhook URL.
+ *
+ * The derivation keeps the host (and port) of the webhook URL and replaces the
+ * path with /ws, because the relay is exposed on the same origin as the
+ * webhook:
+ *
+ *   https://webhook.bunchee.online/telegram -> wss://webhook.bunchee.online/ws
+ *
+ * That only works when the origin serves /ws, i.e. behind the reverse proxy
+ * that maps /ws to the relay port (nginx: location /ws -> 127.0.0.1:8444).
+ * When the webhook URL addresses the application DIRECTLY, the relay listens
+ * on WS_PORT (default 8444), not on the HTTP port - use RELAY_WS_URL or
+ * keys/relay-ws-url.txt for that setup.
+ */
+export function deriveRelayWsUrl(webhookUrl) {
+    const trimmed = webhookUrl?.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = new URL(trimmed);
+        if (!parsed.host)
+            return null;
+        const secure = parsed.protocol === "https:" || parsed.protocol === "wss:";
+        const scheme = secure ? "wss:" : "ws:";
+        return `${scheme}//${parsed.host}/ws`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when the value looks like a WebSocket URL.
+ *
+ * Credentials ("wss://user:pass@host") and query strings are rejected: the
+ * resolved URL is written to the log, and neither belongs there.
+ */
+export function isRelayWsUrl(value) {
+    const trimmed = value?.trim() ?? "";
+    if (!/^wss?:\/\//i.test(trimmed))
+        return false;
+    if (trimmed.includes("@") || trimmed.includes("?"))
+        return false;
+    try {
+        const parsed = new URL(trimmed);
+        if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:")
+            return false;
+        return parsed.host.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function defaultReadFile(path) {
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Host of a URL, or an empty string when it cannot be parsed. */
+function hostOf(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return "";
+    }
+}
+/** True for hosts that address the machine itself. */
+function isLoopbackHost(host) {
+    const name = host.replace(/:\d+$/, "").replace(/^\[|\]$/g, "").toLowerCase();
+    return name === "127.0.0.1" || name === "localhost" || name === "::1" || name.startsWith("127.");
+}
+/**
+ * Transport warnings for a resolved URL.
+ *
+ * A plaintext ws:// URL to a remote host sends the auth token in cleartext.
+ */
+function transportNotes(url) {
+    if (!url.toLowerCase().startsWith("ws://"))
+        return [];
+    if (isLoopbackHost(hostOf(url)))
+        return [];
+    return [
+        "the relay url is plaintext (ws://) for a remote host - the auth token is sent unencrypted, use wss://",
+    ];
+}
+/**
+ * Resolve the WebSocket URL: env -> dedicated key file -> derived from the
+ * telegram webhook url. The first usable source wins; a source that holds a
+ * rejected value is reported so the operator can see why it was skipped.
+ */
+function resolveUrl(env, readKey) {
+    const rejected = [];
+    const notes = [];
+    const envUrl = env.RELAY_WS_URL?.trim();
+    if (envUrl) {
+        if (isRelayWsUrl(envUrl)) {
+            notes.push(...transportNotes(envUrl));
+            return { url: envUrl, source: "env RELAY_WS_URL", rejected, notes };
+        }
+        rejected.push("env RELAY_WS_URL (not a ws:// or wss:// URL)");
+    }
+    const fileUrl = readKey("relay-ws-url.txt");
+    if (fileUrl) {
+        if (isRelayWsUrl(fileUrl)) {
+            notes.push(...transportNotes(fileUrl));
+            return { url: fileUrl, source: "keys/relay-ws-url.txt", rejected, notes };
+        }
+        rejected.push("keys/relay-ws-url.txt (not a ws:// or wss:// URL)");
+    }
+    const webhookUrl = readKey("telegram-webhook-url.txt");
+    const derived = webhookUrl ? deriveRelayWsUrl(webhookUrl) : null;
+    if (derived) {
+        if (isLoopbackHost(hostOf(derived))) {
+            notes.push("derived url points at a loopback host: the relay listens on WS_PORT (default 8444), not on the webhook port - set RELAY_WS_URL or keys/relay-ws-url.txt");
+        }
+        notes.push(...transportNotes(derived));
+        return { url: derived, source: "keys/telegram-webhook-url.txt (derived)", rejected, notes };
+    }
+    if (webhookUrl) {
+        rejected.push("keys/telegram-webhook-url.txt (no ws:// or wss:// URL could be derived)");
+    }
+    return { url: null, source: null, rejected, notes };
+}
+/** Resolve the auth token: env -> dedicated key file -> webhook secret. */
+function resolveToken(env, readKey) {
+    const envToken = env.RELAY_AUTH_TOKEN?.trim();
+    if (envToken) {
+        return { token: envToken, source: "env RELAY_AUTH_TOKEN" };
+    }
+    const fileToken = readKey("relay-auth-token.txt");
+    if (fileToken) {
+        return { token: fileToken, source: "keys/relay-auth-token.txt" };
+    }
+    const secret = readKey("telegram-webhook-secret.txt");
+    if (secret) {
+        return { token: secret, source: "keys/telegram-webhook-secret.txt" };
+    }
+    return { token: null, source: null };
+}
+/**
+ * Resolve the relay WebSocket URL and auth token.
+ *
+ * The first non-empty source wins. A blank file counts as missing (an empty
+ * value is a configuration mistake, not a valid endpoint). A source that holds
+ * a value which was REJECTED is reported in `missing` so the operator can see
+ * why the resolver moved on.
+ */
+export function resolveRelayEndpoint(options) {
+    const env = options.env ?? process.env;
+    const read = options.readFile ?? defaultReadFile;
+    const readKey = (name) => {
+        try {
+            const raw = read(join(options.keysDir, name));
+            const value = raw?.trim();
+            return value ? value : undefined;
+        }
+        catch {
+            // An unreadable key file is treated as absent - the source list in
+            // `missing` tells the operator where to look.
+            return undefined;
+        }
+    };
+    const urlResolution = resolveUrl(env, readKey);
+    const tokenResolution = resolveToken(env, readKey);
+    const missing = [];
+    if (!urlResolution.url) {
+        missing.push(`url not resolved (looked at ${RELAY_URL_SOURCES.join(", ")})`);
+    }
+    if (!tokenResolution.token) {
+        missing.push(`token not resolved (looked at ${RELAY_TOKEN_SOURCES.join(", ")})`);
+    }
+    for (const reason of urlResolution.rejected) {
+        missing.push(`rejected source: ${reason}`);
+    }
+    return {
+        url: urlResolution.url,
+        urlSource: urlResolution.source,
+        token: tokenResolution.token,
+        tokenSource: tokenResolution.source,
+        missing,
+        notes: urlResolution.notes,
+    };
+}
+/**
+ * Log-safe description of a resolution (contains no token value).
+ */
+export function describeRelayEndpoint(resolution) {
+    const parts = [];
+    parts.push(resolution.url ? `url from ${resolution.urlSource}` : "url NOT resolved");
+    parts.push(resolution.token ? `token from ${resolution.tokenSource}` : "token NOT resolved");
+    let description = parts.join(", ");
+    if (resolution.notes.length > 0) {
+        description += ` (${resolution.notes.join("; ")})`;
+    }
+    return description;
+}

package/packages/relay/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/relay",
-  "version": "1.1.387",
+  "version": "1.1.388",
   "type": "module",
   "description": "Cloud relay for remote access - T3 Connect style for pi-harness",
   "main": "./dist/index.js",

package/packages/relay/src/index.ts

@@ -17,6 +17,23 @@ export type { RelayServerOptions } from './server.js';
 export { RelayClient } from './client.js';
 export type { RelayClientCallbacks } from './client.js';
 
+// Endpoint resolution (relay URL + auth token discovery)
+export {
+  resolveRelayEndpoint,
+  deriveRelayWsUrl,
+  isRelayWsUrl,
+  describeRelayEndpoint,
+} from './relay-endpoint.js';
+export type {
+  RelayEndpointEnv,
+  RelayEndpointResolution,
+  ResolveRelayEndpointOptions,
+} from './relay-endpoint.js';
+export {
+  RELAY_URL_SOURCES,
+  RELAY_TOKEN_SOURCES,
+} from './relay-endpoint.js';
+
 // Types
 export {
   PROTOCOL_VERSION,