@n24q02m/hull 0.0.0-stage → 0.4.0-beta.9

package/build/relay/browser.js

@@ -0,0 +1,121 @@
+/**
+ * Cross-platform browser opening with WSL detection.
+ */
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+// Dedupe repeated tryOpenBrowser calls for the same URL. OAuth verification
+// URLs are stable so a retry loop would otherwise spawn a new tab per attempt.
+// Keep a 5-minute window per URL.
+const BROWSER_OPEN_DEDUPE_WINDOW_MS = 5 * 60 * 1000;
+const recentBrowserOpens = new Map();
+/**
+ * Read an on/off environment flag: set, and not `''` / `'false'` / `'0'`.
+ *
+ * One rule for all three variables the guard below reads, deliberately. `CI` has to
+ * follow this rule because it is a variable we READ from someone else's environment and
+ * `CI=false` is a real idiom for "do not apply CI behavior" (Create React App, Netlify) —
+ * the `ci-info` package uses the same rule. Our own two then follow it as well, for two
+ * reasons: a plain truthy-string check makes `MCP_NO_BROWSER=false` SUPPRESS the browser,
+ * which is wrong under every reading of a negative variable name (writing `=false` means
+ * "no, don't no-browser" — that person is asking for auto-open and would be blocked
+ * silently); and two rules inside one `if` is a trap for whoever reads it next.
+ */
+function envFlag(name) {
+    const value = process.env[name];
+    return value !== undefined && value !== '' && value !== 'false' && value !== '0';
+}
+async function isWsl() {
+    try {
+        const version = await readFile('/proc/version', 'utf-8');
+        const lower = version.toLowerCase();
+        return lower.includes('microsoft') || lower.includes('wsl');
+    }
+    catch {
+        return false;
+    }
+}
+function encodePowerShellCommand(command) {
+    return Buffer.from(command, 'utf16le').toString('base64');
+}
+async function openInPowerShell(url) {
+    try {
+        const base64Url = Buffer.from(url, 'utf8').toString('base64');
+        const command = `$url = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('${base64Url}')); Start-Process $url`;
+        const encodedCommand = encodePowerShellCommand(command);
+        await execFileAsync('powershell.exe', ['-NoProfile', '-EncodedCommand', encodedCommand]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function openInWsl(url) {
+    // Try powershell.exe -EncodedCommand first (safer due to Base64 encoding)
+    const result = await openInPowerShell(url);
+    if (result) {
+        return true;
+    }
+    // Fallback to wslview (from wslu package, commonly available)
+    try {
+        await execFileAsync('wslview', [url]);
+        return true;
+    }
+    catch {
+        /* fall through */
+    }
+    return false;
+}
+/**
+ * Try to open URL in default browser. Returns true if likely succeeded.
+ *
+ * Detection order:
+ * 1. win32: powershell.exe -EncodedCommand
+ * 2. darwin: `open` command
+ * 3. linux: check WSL then `xdg-open`
+ *
+ * Never throws. Returns false on failure.
+ */
+export async function tryOpenBrowser(url) {
+    try {
+        // Env-guard: suppress auto-open in headless / CI / autonomous-test contexts so a
+        // relay/clean-state server never hijacks the user's real browser with /authorize?nonce
+        // or 127.0.0.1 tabs. Set MCP_NO_BROWSER=1 or NO_BROWSER=1 to disable it explicitly;
+        // `CI` counts too because every CI provider sets it (GitHub Actions: CI=true) and a
+        // build agent has no browser to hijack.
+        if (envFlag('MCP_NO_BROWSER') || envFlag('NO_BROWSER') || envFlag('CI')) {
+            return false;
+        }
+        // Validate URL
+        if (!/^https?:\/\/[a-zA-Z0-9-._~:/?#[\]@!&'*+,;=%]+$/i.test(url)) {
+            return false;
+        }
+        const lastOpened = recentBrowserOpens.get(url);
+        if (lastOpened !== undefined && Date.now() - lastOpened < BROWSER_OPEN_DEDUPE_WINDOW_MS) {
+            return true;
+        }
+        recentBrowserOpens.set(url, Date.now());
+        const platform = process.platform;
+        if (platform === 'win32') {
+            return openInPowerShell(url);
+        }
+        if (platform === 'darwin') {
+            await execFileAsync('open', [url]);
+            return true;
+        }
+        // linux
+        if (await isWsl()) {
+            const result = await openInWsl(url);
+            if (result)
+                return true;
+            // Fall through to xdg-open
+        }
+        await execFileAsync('xdg-open', [url]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=browser.js.map

package/build/relay/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/relay/browser.ts"],"names":[],"mappings":"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"}

package/build/relay/client.d.ts

@@ -0,0 +1,36 @@
+import type { RelayConfigSchema } from '../schema/types.js';
+export declare function generatePassphrase(wordCount?: number): string;
+export interface RelaySession {
+    sessionId: string;
+    keyPair: CryptoKeyPair;
+    passphrase: string;
+    relayUrl: string;
+}
+export declare function createSession(relayBaseUrl: string, serverName: string, schema: RelayConfigSchema): Promise<RelaySession>;
+export declare function pollForResult(relayBaseUrl: string, session: RelaySession, intervalMs?: number, timeoutMs?: number): Promise<Record<string, string>>;
+export declare function sendMessage(relayBaseUrl: string, sessionId: string, message: {
+    type: string;
+    text: string;
+    data?: Record<string, unknown>;
+}): Promise<string>;
+export declare function pollForResponses(relayBaseUrl: string, sessionId: string, messageId: string, intervalMs?: number, timeoutMs?: number): Promise<string>;
+/**
+ * Notify the browser that relay setup is complete, then clean up the session.
+ *
+ * The browser polls ``/api/sessions/:id/messages`` every 2s and stops on the
+ * first ``type:'complete'`` message. If the caller deletes the session before
+ * that poll lands, the browser sees 404 on its next fetch and the UI stalls
+ * on "Waiting for server...". This helper sends the ``complete`` message,
+ * then schedules the DELETE after a grace period long enough to cover a few
+ * poll cycles, and unref's the cleanup timer so it doesn't block process
+ * shutdown. If the process exits before the timer fires, the relay server's
+ * 10-minute TTL reclaims the session.
+ *
+ * Errors from ``sendMessage`` are logged via ``console.error`` and swallowed
+ * — the helper is a best-effort post-setup notification and must not fail
+ * the caller's primary flow.
+ */
+export declare function notifyComplete(relayBaseUrl: string, sessionId: string, text?: string, options?: {
+    gracePeriodMs?: number;
+}): Promise<void>;
+//# sourceMappingURL=client.d.ts.map

package/build/relay/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/relay/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAM3D,wBAAgB,kBAAkB,CAAC,SAAS,SAAI,GAAG,MAAM,CAkBxD;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,aAAa,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,wBAAsB,aAAa,CACjC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,YAAY,CAAC,CAgBvB;AAED,wBAAsB,aAAa,CACjC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,YAAY,EACrB,UAAU,SAAO,EACjB,SAAS,SAAU,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAwCjC;AAED,wBAAsB,WAAW,CAC/B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACtE,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAsB,gBAAgB,CACpC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,UAAU,SAAO,EACjB,SAAS,SAAU,GAClB,OAAO,CAAC,MAAM,CAAC,CA2BjB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAClC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,MAA0B,EAChC,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/build/relay/client.js

@@ -0,0 +1,135 @@
+import { decrypt } from '../crypto/aes.js';
+import { deriveSharedSecret, exportPublicKey, generateKeyPair, importPublicKey } from '../crypto/ecdh.js';
+import { deriveAesKey } from '../crypto/kdf.js';
+import { WORDLIST } from './wordlist.js';
+// Single fallback buffer for rejection sampling, reused to minimize GC
+const fallbackBuffer = new Uint16Array(1);
+export function generatePassphrase(wordCount = 4) {
+    const words = [];
+    const max = Math.floor(0x10000 / WORDLIST.length) * WORDLIST.length; // rejection threshold
+    // Optimization: Batch random generation for all words at once
+    const buffer = new Uint16Array(wordCount);
+    crypto.getRandomValues(buffer);
+    for (let i = 0; i < wordCount; i++) {
+        let index = buffer[i];
+        while (index >= max) {
+            // Reject biased values and resample
+            crypto.getRandomValues(fallbackBuffer);
+            index = fallbackBuffer[0];
+        }
+        words.push(WORDLIST[index % WORDLIST.length]);
+    }
+    return words.join('-');
+}
+export async function createSession(relayBaseUrl, serverName, schema) {
+    const sessionId = Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString('hex');
+    const keyPair = await generateKeyPair();
+    const passphrase = generatePassphrase();
+    const response = await fetch(`${relayBaseUrl}/api/sessions`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ sessionId, serverName, schema })
+    });
+    if (!response.ok)
+        throw new Error(`Relay session creation failed: ${response.status}`);
+    const pubKeyBase64 = await exportPublicKey(keyPair.publicKey);
+    const relayUrl = `${relayBaseUrl}/authorize?s=${sessionId}#k=${pubKeyBase64}&p=${encodeURIComponent(passphrase)}`;
+    return { sessionId, keyPair, passphrase, relayUrl };
+}
+export async function pollForResult(relayBaseUrl, session, intervalMs = 2000, timeoutMs = 600_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const response = await fetch(`${relayBaseUrl}/api/sessions/${session.sessionId}`);
+        if (response.status === 200) {
+            const body = await response.json();
+            if (body.status === 'skipped') {
+                // Cleanup session
+                await fetch(`${relayBaseUrl}/api/sessions/${session.sessionId}`, {
+                    method: 'DELETE'
+                }).catch(() => { });
+                throw new Error('RELAY_SKIPPED');
+            }
+            const { browserPub, ciphertext, iv, tag } = body.result ?? body;
+            const browserKey = await importPublicKey(browserPub);
+            const sharedSecret = await deriveSharedSecret(session.keyPair.privateKey, browserKey);
+            const aesKey = await deriveAesKey(sharedSecret, session.passphrase);
+            const plaintext = await decrypt(aesKey, new Uint8Array(Buffer.from(ciphertext, 'base64')), new Uint8Array(Buffer.from(iv, 'base64')), new Uint8Array(Buffer.from(tag, 'base64')));
+            // Don't delete session here — keep alive for bidirectional messaging.
+            // Session auto-expires via TTL (10 min). Caller can delete manually if needed.
+            return JSON.parse(plaintext);
+        }
+        if (response.status === 404)
+            throw new Error('Session expired or not found');
+        if (response.status !== 202)
+            throw new Error(`Unexpected status: ${response.status}`);
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+    throw new Error('Relay setup timed out');
+}
+export async function sendMessage(relayBaseUrl, sessionId, message) {
+    const response = await fetch(`${relayBaseUrl}/api/sessions/${sessionId}/messages`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(message)
+    });
+    if (!response.ok)
+        throw new Error(`Failed to send message: ${response.status}`);
+    const body = await response.json();
+    return body.id;
+}
+export async function pollForResponses(relayBaseUrl, sessionId, messageId, intervalMs = 2000, timeoutMs = 300_000) {
+    const deadline = Date.now() + timeoutMs;
+    let lastSeenCount = 0;
+    while (Date.now() < deadline) {
+        const response = await fetch(`${relayBaseUrl}/api/sessions/${sessionId}/responses`);
+        if (!response.ok)
+            throw new Error(`Failed to poll responses: ${response.status}`);
+        const body = await response.json();
+        const responses = body.responses;
+        // Optimization: The responses array is append-only.
+        // Instead of doing O(N) array.find() scanning from the beginning,
+        // manually loop backwards stopping at the last seen count.
+        if (responses) {
+            for (let i = responses.length - 1; i >= lastSeenCount; i--) {
+                if (responses[i].messageId === messageId) {
+                    return responses[i].value;
+                }
+            }
+            lastSeenCount = responses.length;
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+    throw new Error('Timed out waiting for response');
+}
+/**
+ * Notify the browser that relay setup is complete, then clean up the session.
+ *
+ * The browser polls ``/api/sessions/:id/messages`` every 2s and stops on the
+ * first ``type:'complete'`` message. If the caller deletes the session before
+ * that poll lands, the browser sees 404 on its next fetch and the UI stalls
+ * on "Waiting for server...". This helper sends the ``complete`` message,
+ * then schedules the DELETE after a grace period long enough to cover a few
+ * poll cycles, and unref's the cleanup timer so it doesn't block process
+ * shutdown. If the process exits before the timer fires, the relay server's
+ * 10-minute TTL reclaims the session.
+ *
+ * Errors from ``sendMessage`` are logged via ``console.error`` and swallowed
+ * — the helper is a best-effort post-setup notification and must not fail
+ * the caller's primary flow.
+ */
+export async function notifyComplete(relayBaseUrl, sessionId, text = 'Setup complete!', options = {}) {
+    try {
+        await sendMessage(relayBaseUrl, sessionId, { type: 'complete', text });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[hull] Failed to send relay 'complete' message: ${msg}`);
+        return;
+    }
+    const gracePeriodMs = options.gracePeriodMs ?? 5000;
+    const timer = setTimeout(() => {
+        fetch(`${relayBaseUrl}/api/sessions/${sessionId}`, { method: 'DELETE' }).catch(() => { });
+    }, gracePeriodMs);
+    timer.unref?.();
+}
+//# sourceMappingURL=client.js.map

package/build/relay/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/relay/client.ts"],"names":[],"mappings":"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"}

package/build/relay/session.d.ts

@@ -0,0 +1,12 @@
+export interface ActiveFormSession {
+    token: string;
+    clientId: string;
+    startedAt: Date;
+    expiresAt: Date;
+}
+export declare function claimSession(clientId: string): ActiveFormSession;
+export declare function releaseSession(): void;
+export declare function isSessionActive(): boolean;
+export declare function validateSessionToken(token: string): boolean;
+export declare function getActiveSession(): ActiveFormSession | null;
+//# sourceMappingURL=session.d.ts.map

package/build/relay/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/relay/session.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CAChB;AAQD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAYhE;AAED,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED,wBAAgB,eAAe,IAAI,OAAO,CAOzC;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAW3D;AAED,wBAAgB,gBAAgB,IAAI,iBAAiB,GAAG,IAAI,CAO3D"}

package/build/relay/session.js

@@ -0,0 +1,55 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+const SESSION_TTL_MS = 30 * 60 * 1000;
+const TOKEN_BYTES = 32;
+let state = null;
+function now() {
+    return new Date();
+}
+export function claimSession(clientId) {
+    if (state !== null && state.expiresAt > now()) {
+        return state;
+    }
+    const startedAt = now();
+    state = {
+        token: randomBytes(TOKEN_BYTES).toString('base64url'),
+        clientId,
+        startedAt,
+        expiresAt: new Date(startedAt.getTime() + SESSION_TTL_MS)
+    };
+    return state;
+}
+export function releaseSession() {
+    state = null;
+}
+export function isSessionActive() {
+    if (state === null)
+        return false;
+    if (state.expiresAt <= now()) {
+        state = null;
+        return false;
+    }
+    return true;
+}
+export function validateSessionToken(token) {
+    if (state === null)
+        return false;
+    if (state.expiresAt <= now()) {
+        state = null;
+        return false;
+    }
+    const a = Buffer.from(state.token);
+    const b = Buffer.from(token);
+    const isLengthEqual = a.length === b.length;
+    const compareB = isLengthEqual ? b : a;
+    return timingSafeEqual(a, compareB) && isLengthEqual;
+}
+export function getActiveSession() {
+    if (state === null)
+        return null;
+    if (state.expiresAt <= now()) {
+        state = null;
+        return null;
+    }
+    return state;
+}
+//# sourceMappingURL=session.js.map

package/build/relay/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/relay/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE1D,MAAM,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;AACrC,MAAM,WAAW,GAAG,EAAE,CAAA;AAStB,IAAI,KAAK,GAA6B,IAAI,CAAA;AAE1C,SAAS,GAAG;IACV,OAAO,IAAI,IAAI,EAAE,CAAA;AACnB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,SAAS,GAAG,GAAG,EAAE,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAA;IACd,CAAC;IACD,MAAM,SAAS,GAAG,GAAG,EAAE,CAAA;IACvB,KAAK,GAAG;QACN,KAAK,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;QACrD,QAAQ;QACR,SAAS;QACT,SAAS,EAAE,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,cAAc,CAAC;KAC1D,CAAA;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,KAAK,GAAG,IAAI,CAAA;AACd,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IAChC,IAAI,KAAK,CAAC,SAAS,IAAI,GAAG,EAAE,EAAE,CAAC;QAC7B,KAAK,GAAG,IAAI,CAAA;QACZ,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IAChC,IAAI,KAAK,CAAC,SAAS,IAAI,GAAG,EAAE,EAAE,CAAC;QAC7B,KAAK,GAAG,IAAI,CAAA;QACZ,OAAO,KAAK,CAAA;IACd,CAAC;IACD,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAClC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAC5B,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,CAAA;IAC3C,MAAM,QAAQ,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACtC,OAAO,eAAe,CAAC,CAAC,EAAE,QAAQ,CAAC,IAAI,aAAa,CAAA;AACtD,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAA;IAC/B,IAAI,KAAK,CAAC,SAAS,IAAI,GAAG,EAAE,EAAE,CAAC;QAC7B,KAAK,GAAG,IAAI,CAAA;QACZ,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

package/build/relay/tool-helpers.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Helper to register `config__open_relay` MCP tool — HTTP-only mode.
+ *
+ * After the stdio-pure + http-multi-user split, the relay config form is
+ * served by the HTTP server itself at ``<PUBLIC_URL>/authorize``. The
+ * ``config__open_relay`` tool directs the user to that URL.
+ *
+ * When the connected client declares URL-mode elicitation
+ * (``capabilities.elicitation.url``, SEP-1036), the tool asks the client to
+ * present a consent prompt and open the URL via ``Server.elicitInput`` so the
+ * credential form is opened out-of-band without the LLM in the loop. Clients
+ * that do NOT declare the capability fall back to the legacy behaviour: the
+ * tool returns the URL and best-effort opens the user's default browser
+ * server-side. There is no daemon-bridge discovery, no respawn, and no
+ * session deduplication — the HTTP server's own session tracking handles
+ * concurrent setup attempts.
+ *
+ * In stdio mode, the relay form does not exist; the tool returns
+ * ``stdio_unsupported`` so plugin code can render a "switch to HTTP mode"
+ * message instead of misleading the user with an unreachable URL.
+ */
+import type { ClientCapabilities, ElicitRequestURLParams, ElicitResult } from '@modelcontextprotocol/sdk/types.js';
+export interface OpenRelayResult {
+    url: string;
+    browserOpened: boolean;
+    status: 'configured' | 'unconfigured' | 'expired' | 'session_active' | 'stdio_unsupported';
+    elicitation?: 'accepted' | 'declined' | 'cancelled';
+}
+/**
+ * Minimal surface required to drive URL-mode elicitation. Satisfied by the
+ * low-level `Server` from `@modelcontextprotocol/sdk` (`mcp.server`), which
+ * exposes both `getClientCapabilities` and `elicitInput`.
+ */
+export interface ElicitationServer {
+    getClientCapabilities: () => ClientCapabilities | undefined;
+    elicitInput: (params: ElicitRequestURLParams) => Promise<ElicitResult>;
+}
+export interface OpenRelayHandlerOptions {
+    serverName: string;
+    publicUrl: string | null;
+    elicitation?: ElicitationServer;
+}
+/**
+ * Build the `open_relay` handler closure. Tests can call
+ * ``buildOpenRelayHandler({ serverName, publicUrl })`` directly without
+ * needing a real MCP server instance.
+ *
+ * When `elicitation` is supplied AND the client declared URL-mode
+ * elicitation, the handler drives `elicitInput` and returns the accept /
+ * decline / cancel outcome. Otherwise it returns the legacy dict
+ * (`{ url, browserOpened, status }`) unchanged.
+ */
+export declare function buildOpenRelayHandler(options: OpenRelayHandlerOptions): () => Promise<OpenRelayResult>;
+/**
+ * Minimal shape we require from the MCP server instance to register the
+ * tool. Both `@modelcontextprotocol/sdk`'s `McpServer.tool` and the
+ * FastMCP-style helpers used in consumer servers conform to this surface.
+ */
+export interface ToolRegistrar {
+    tool: (config: {
+        name: string;
+        description?: string;
+    }, handler: () => Promise<OpenRelayResult>) => void;
+}
+/**
+ * Register `config__open_relay` on the given MCP server instance.
+ *
+ * Consumer servers add this single line in their tool registry after the
+ * other `config__*` registrations:
+ *
+ * ```ts
+ * import { registerOpenRelayTool } from '@n24q02m/hull'
+ * registerOpenRelayTool(mcp, SERVER_NAME, PUBLIC_URL, mcp.server)
+ * ```
+ *
+ * Pass ``null`` for ``publicUrl`` when the server is running in stdio mode;
+ * the tool will return ``status: 'stdio_unsupported'`` so the caller can
+ * surface a clear "switch to HTTP mode" message.
+ *
+ * Pass the low-level `Server` (`mcp.server`) as ``elicitation`` to enable
+ * URL-mode elicitation for capable clients. When omitted, the tool keeps
+ * the legacy browser-open behaviour for every client.
+ */
+export declare function registerOpenRelayTool(mcp: ToolRegistrar, serverName: string, publicUrl: string | null, elicitation?: ElicitationServer): void;
+//# sourceMappingURL=tool-helpers.d.ts.map

package/build/relay/tool-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-helpers.d.ts","sourceRoot":"","sources":["../../src/relay/tool-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AAGlH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,OAAO,CAAA;IACtB,MAAM,EAAE,YAAY,GAAG,cAAc,GAAG,SAAS,GAAG,gBAAgB,GAAG,mBAAmB,CAAA;IAC1F,WAAW,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,WAAW,CAAA;CACpD;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,qBAAqB,EAAE,MAAM,kBAAkB,GAAG,SAAS,CAAA;IAC3D,WAAW,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAA;CACvE;AAED,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,WAAW,CAAC,EAAE,iBAAiB,CAAA;CAChC;AAaD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,OAAO,CAAC,eAAe,CAAC,CAyBtG;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,KAAK,IAAI,CAAA;CACxG;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,aAAa,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,WAAW,CAAC,EAAE,iBAAiB,GAC9B,IAAI,CAiBN"}

package/build/relay/tool-helpers.js

@@ -0,0 +1,103 @@
+/**
+ * Helper to register `config__open_relay` MCP tool — HTTP-only mode.
+ *
+ * After the stdio-pure + http-multi-user split, the relay config form is
+ * served by the HTTP server itself at ``<PUBLIC_URL>/authorize``. The
+ * ``config__open_relay`` tool directs the user to that URL.
+ *
+ * When the connected client declares URL-mode elicitation
+ * (``capabilities.elicitation.url``, SEP-1036), the tool asks the client to
+ * present a consent prompt and open the URL via ``Server.elicitInput`` so the
+ * credential form is opened out-of-band without the LLM in the loop. Clients
+ * that do NOT declare the capability fall back to the legacy behaviour: the
+ * tool returns the URL and best-effort opens the user's default browser
+ * server-side. There is no daemon-bridge discovery, no respawn, and no
+ * session deduplication — the HTTP server's own session tracking handles
+ * concurrent setup attempts.
+ *
+ * In stdio mode, the relay form does not exist; the tool returns
+ * ``stdio_unsupported`` so plugin code can render a "switch to HTTP mode"
+ * message instead of misleading the user with an unreachable URL.
+ */
+import { randomUUID } from 'node:crypto';
+import { tryOpenBrowser } from './browser.js';
+// Maps the client's ElicitResult.action to the tool's outcome field.
+const ELICIT_ACTION_MAP = {
+    accept: 'accepted',
+    decline: 'declined',
+    cancel: 'cancelled'
+};
+function clientSupportsUrlElicitation(server) {
+    return server.getClientCapabilities()?.elicitation?.url != null;
+}
+/**
+ * Build the `open_relay` handler closure. Tests can call
+ * ``buildOpenRelayHandler({ serverName, publicUrl })`` directly without
+ * needing a real MCP server instance.
+ *
+ * When `elicitation` is supplied AND the client declared URL-mode
+ * elicitation, the handler drives `elicitInput` and returns the accept /
+ * decline / cancel outcome. Otherwise it returns the legacy dict
+ * (`{ url, browserOpened, status }`) unchanged.
+ */
+export function buildOpenRelayHandler(options) {
+    return async function openRelay() {
+        if (!options.publicUrl) {
+            return { url: '', browserOpened: false, status: 'stdio_unsupported' };
+        }
+        const url = `${options.publicUrl.replace(/\/$/, '')}/authorize`;
+        const { elicitation } = options;
+        if (elicitation && clientSupportsUrlElicitation(elicitation)) {
+            const message = `Open the ${options.serverName} configuration page to enter your credentials securely in your browser.`;
+            const result = await elicitation.elicitInput({
+                mode: 'url',
+                message,
+                url,
+                elicitationId: randomUUID()
+            });
+            return {
+                url,
+                browserOpened: false,
+                status: 'unconfigured',
+                elicitation: ELICIT_ACTION_MAP[result.action] ?? 'accepted'
+            };
+        }
+        const opened = await tryOpenBrowser(url);
+        return { url, browserOpened: !!opened, status: 'unconfigured' };
+    };
+}
+/**
+ * Register `config__open_relay` on the given MCP server instance.
+ *
+ * Consumer servers add this single line in their tool registry after the
+ * other `config__*` registrations:
+ *
+ * ```ts
+ * import { registerOpenRelayTool } from '@n24q02m/hull'
+ * registerOpenRelayTool(mcp, SERVER_NAME, PUBLIC_URL, mcp.server)
+ * ```
+ *
+ * Pass ``null`` for ``publicUrl`` when the server is running in stdio mode;
+ * the tool will return ``status: 'stdio_unsupported'`` so the caller can
+ * surface a clear "switch to HTTP mode" message.
+ *
+ * Pass the low-level `Server` (`mcp.server`) as ``elicitation`` to enable
+ * URL-mode elicitation for capable clients. When omitted, the tool keeps
+ * the legacy browser-open behaviour for every client.
+ */
+export function registerOpenRelayTool(mcp, serverName, publicUrl, elicitation) {
+    const handler = buildOpenRelayHandler({ serverName, publicUrl, elicitation });
+    mcp.tool({
+        name: 'config__open_relay',
+        // Deliberately conditional. The handler returns `browserOpened: false`
+        // whenever no browser could be launched (headless, CI, the env-guard, no
+        // desktop session), and this text is read by a model that then speaks for
+        // the tool. "Open the ... form in the user's browser" reads as a
+        // guarantee, so a model can report "opened it in your browser" while the
+        // result says otherwise -- the user is then waiting on a tab that will
+        // never appear. The URL is what the tool always delivers; the browser is
+        // a convenience on top, and the wording says so in that order.
+        description: `Get the relay configuration URL for ${serverName}, opening it in the user's browser when possible.`
+    }, handler);
+}
+//# sourceMappingURL=tool-helpers.js.map

package/build/relay/tool-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-helpers.js","sourceRoot":"","sources":["../../src/relay/tool-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAyB7C,qEAAqE;AACrE,MAAM,iBAAiB,GAA0D;IAC/E,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,UAAU;IACnB,MAAM,EAAE,WAAW;CACpB,CAAA;AAED,SAAS,4BAA4B,CAAC,MAAyB;IAC7D,OAAO,MAAM,CAAC,qBAAqB,EAAE,EAAE,WAAW,EAAE,GAAG,IAAI,IAAI,CAAA;AACjE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAgC;IACpE,OAAO,KAAK,UAAU,SAAS;QAC7B,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YACvB,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAA;QACvE,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAA;QAC/D,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAA;QAC/B,IAAI,WAAW,IAAI,4BAA4B,CAAC,WAAW,CAAC,EAAE,CAAC;YAC7D,MAAM,OAAO,GAAG,YAAY,OAAO,CAAC,UAAU,yEAAyE,CAAA;YACvH,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,WAAW,CAAC;gBAC3C,IAAI,EAAE,KAAK;gBACX,OAAO;gBACP,GAAG;gBACH,aAAa,EAAE,UAAU,EAAE;aAC5B,CAAC,CAAA;YACF,OAAO;gBACL,GAAG;gBACH,aAAa,EAAE,KAAK;gBACpB,MAAM,EAAE,cAAc;gBACtB,WAAW,EAAE,iBAAiB,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,UAAU;aAC5D,CAAA;QACH,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,GAAG,CAAC,CAAA;QACxC,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,CAAA;IACjE,CAAC,CAAA;AACH,CAAC;AAWD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAAkB,EAClB,UAAkB,EAClB,SAAwB,EACxB,WAA+B;IAE/B,MAAM,OAAO,GAAG,qBAAqB,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,CAAA;IAC7E,GAAG,CAAC,IAAI,CACN;QACE,IAAI,EAAE,oBAAoB;QAC1B,uEAAuE;QACvE,yEAAyE;QACzE,0EAA0E;QAC1E,iEAAiE;QACjE,yEAAyE;QACzE,uEAAuE;QACvE,yEAAyE;QACzE,+DAA+D;QAC/D,WAAW,EAAE,uCAAuC,UAAU,mDAAmD;KAClH,EACD,OAAO,CACR,CAAA;AACH,CAAC"}

package/build/relay/wordlist.d.ts

@@ -0,0 +1,2 @@
+export declare const WORDLIST: string[];
+//# sourceMappingURL=wordlist.d.ts.map

package/build/relay/wordlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wordlist.d.ts","sourceRoot":"","sources":["../../src/relay/wordlist.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,QAAQ,EAAE,MAAM,EAimP5B,CAAA"}