@stelis/say-ur-intent 0.0.0 → 0.0.2

package/dist/review-server/settingsApi.js

@@ -0,0 +1,182 @@
+import { LocalDataError } from "../core/activity/localDataService.js";
+import { LocalSettingsError } from "../core/preferences/preferencesStore.js";
+import { validateHostOrigin } from "./middleware/hostOrigin.js";
+import { readReviewToken } from "./middleware/reviewToken.js";
+import { HttpError, MAX_JSON_BODY_BYTES, readJsonBody, sendJson } from "./http.js";
+import { ALLOWED_HOSTNAMES } from "./reviewServerPolicy.js";
+import { walletIdentitySessionResponse } from "./walletIdentityResponse.js";
+const MAX_SETTINGS_BODY_BYTES = MAX_JSON_BODY_BYTES;
+const MAX_IMPORT_BODY_BYTES = 16 * 1024 * 1024;
+export async function routeSettingsApi(request, response, options, url, matches) {
+    const hostOrigin = validateHostOrigin(request, { allowedHostnames: ALLOWED_HOSTNAMES });
+    if (!hostOrigin.ok) {
+        sendJson(response, hostOrigin.status, { error: hostOrigin.reason });
+        return;
+    }
+    if (url.searchParams.has("token")) {
+        sendJson(response, 400, { error: "token_query_not_supported" });
+        return;
+    }
+    const settings = requireSettingsDeps(options);
+    const sessionId = matches.status ??
+        matches.walletIdentity ??
+        matches.clearActiveAccount ??
+        matches.setSuiGrpcUrl ??
+        matches.restoreDefaultSuiGrpcUrl ??
+        matches.setSuiGraphqlUrl ??
+        matches.restoreDefaultSuiGraphqlUrl ??
+        matches.exportLocalData ??
+        matches.previewImport ??
+        matches.importLocalData ??
+        matches.resetLocalData;
+    if (!sessionId) {
+        throw new HttpError(404, "not_found");
+    }
+    const token = readReviewToken(request.headers);
+    if (!token || !(await options.store.validateSettingsToken(sessionId, token))) {
+        sendJson(response, 401, { error: "invalid_settings_token" });
+        return;
+    }
+    if (request.method === "GET" && matches.status) {
+        const [localSettings, activeAccount, dataCounts] = await Promise.all([
+            mapLocalSettingsError(() => settings.localSettings.getLocalSettings()),
+            settings.activityStore.getActiveAccount(),
+            settings.localData.getDataCounts()
+        ]);
+        sendJson(response, 200, {
+            settingsSessionId: sessionId,
+            server: settings.serverInfo,
+            localSettings,
+            activeAccount: activeAccount
+                ? {
+                    account: activeAccount.address,
+                    source: activeAccount.source,
+                    setAt: activeAccount.setAt
+                }
+                : undefined,
+            dataCounts,
+            restartRequired: localSettings.suiGrpcUrl.appliesAfter === "mcp_server_restart" ||
+                localSettings.suiGraphqlUrl.appliesAfter === "mcp_server_restart"
+        });
+        return;
+    }
+    if (request.method === "POST" && matches.walletIdentity) {
+        await readJsonBody(request, MAX_SETTINGS_BODY_BYTES);
+        const wallet = await options.store.createWalletIdentitySession();
+        const baseUrl = requestBaseUrl(request);
+        sendJson(response, 200, walletIdentitySessionResponse(wallet, baseUrl));
+        return;
+    }
+    if (request.method === "POST" && matches.clearActiveAccount) {
+        await readJsonBody(request, MAX_SETTINGS_BODY_BYTES);
+        await settings.activityStore.clearActiveAccount();
+        sendJson(response, 200, { status: "cleared" });
+        return;
+    }
+    if (request.method === "POST" && matches.setSuiGrpcUrl) {
+        const body = await readJsonBody(request, MAX_SETTINGS_BODY_BYTES);
+        const urlValue = typeof body.url === "string" ? body.url : undefined;
+        if (!urlValue) {
+            sendJson(response, 400, { error: "input_invalid" });
+            return;
+        }
+        const result = await mapLocalSettingsError(() => settings.localSettings.setSuiGrpcUrl(urlValue));
+        sendJson(response, 200, result);
+        return;
+    }
+    if (request.method === "POST" && matches.restoreDefaultSuiGrpcUrl) {
+        await readJsonBody(request, MAX_SETTINGS_BODY_BYTES);
+        const result = await mapLocalSettingsError(() => settings.localSettings.resetSuiGrpcUrl());
+        sendJson(response, 200, result);
+        return;
+    }
+    if (request.method === "POST" && matches.setSuiGraphqlUrl) {
+        const body = await readJsonBody(request, MAX_SETTINGS_BODY_BYTES);
+        const urlValue = typeof body.url === "string" ? body.url : undefined;
+        if (!urlValue) {
+            sendJson(response, 400, { error: "input_invalid" });
+            return;
+        }
+        const result = await mapLocalSettingsError(() => settings.localSettings.setSuiGraphqlUrl(urlValue));
+        sendJson(response, 200, result);
+        return;
+    }
+    if (request.method === "POST" && matches.restoreDefaultSuiGraphqlUrl) {
+        await readJsonBody(request, MAX_SETTINGS_BODY_BYTES);
+        const result = await mapLocalSettingsError(() => settings.localSettings.resetSuiGraphqlUrl());
+        sendJson(response, 200, result);
+        return;
+    }
+    if (request.method === "GET" && matches.exportLocalData) {
+        const envelope = await mapLocalDataError(() => settings.localData.exportLocalData());
+        sendJson(response, 200, envelope);
+        return;
+    }
+    if (request.method === "POST" && matches.previewImport) {
+        const body = await readJsonBody(request, MAX_IMPORT_BODY_BYTES);
+        const preview = await mapLocalDataError(() => settings.localData.previewImportLocalData(body));
+        sendJson(response, 200, preview);
+        return;
+    }
+    if (request.method === "POST" && matches.importLocalData) {
+        const body = await readJsonBody(request, MAX_IMPORT_BODY_BYTES);
+        const result = await mapLocalDataError(() => settings.localData.importLocalDataReplace(body));
+        await options.store.invalidateAllLocalSessions("local_data_import");
+        sendJson(response, 200, result);
+        return;
+    }
+    if (request.method === "POST" && matches.resetLocalData) {
+        await readJsonBody(request, MAX_SETTINGS_BODY_BYTES);
+        const result = await mapLocalDataError(() => settings.localData.resetLocalData());
+        await options.store.invalidateAllLocalSessions("local_data_reset");
+        sendJson(response, 200, result);
+        return;
+    }
+    sendJson(response, 404, { error: "not_found" });
+}
+function requireSettingsDeps(options) {
+    if (!options.activityStore || !options.localSettings || !options.localData || !options.serverInfo) {
+        throw new HttpError(404, "not_found");
+    }
+    return {
+        activityStore: options.activityStore,
+        localSettings: options.localSettings,
+        localData: options.localData,
+        serverInfo: options.serverInfo
+    };
+}
+function requestBaseUrl(request) {
+    const host = request.headers.host;
+    if (!host) {
+        throw new HttpError(400, "host_required");
+    }
+    return `http://${host}`;
+}
+async function mapLocalSettingsError(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (error instanceof LocalSettingsError) {
+            throw new HttpError(statusForLocalSettingsError(error), error.kind);
+        }
+        throw error;
+    }
+}
+function statusForLocalSettingsError(error) {
+    return error.kind === "input_invalid" ? 400 : 500;
+}
+async function mapLocalDataError(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (error instanceof LocalDataError) {
+            throw new HttpError(statusForLocalDataError(error), error.kind);
+        }
+        throw error;
+    }
+}
+function statusForLocalDataError(error) {
+    return error.kind === "input_invalid" ? 400 : 500;
+}

package/dist/review-server/walletIdentityResponse.js

@@ -0,0 +1,13 @@
+import { walletIdentityPollingHint } from "../core/session/walletIdentity.js";
+export function walletIdentitySessionResponse(wallet, baseUrl) {
+    return {
+        walletSessionId: wallet.session.id,
+        walletUrl: `${baseUrl}/analysis/${wallet.session.id}#${wallet.token}`,
+        status: wallet.session.status,
+        expiresAt: wallet.session.expiresAt,
+        lastActivityAt: wallet.session.lastActivityAt,
+        openTarget: "system_browser",
+        accessScope: "same_machine_loopback",
+        pollingHint: walletIdentityPollingHint()
+    };
+}

package/dist/runtime/config.js

@@ -0,0 +1,103 @@
+import { resolveActivityDatabasePath } from "../core/activity/sqliteActivityStore.js";
+import { DEFAULT_SUI_GRAPHQL_URL, DEFAULT_SUI_GRPC_URL, SUI_MAINNET_CHAIN_IDENTIFIER, parseGraphqlUrl, parseGrpcUrl } from "./suiEndpoint.js";
+import { SETTINGS_APPLIES_AFTER_RESTART } from "../core/preferences/preferencesStore.js";
+export function loadBootConfig(env = process.env) {
+    const network = env.SUI_NETWORK ?? "mainnet";
+    if (network !== "mainnet") {
+        throw new Error("Say Ur Intent product runtime only supports mainnet");
+    }
+    if (env.SUI_RPC_URL) {
+        throw new Error("Sui JSON-RPC endpoint configuration is not supported; use local settings, SUI_GRPC_URL for gRPC, or SUI_GRAPHQL_URL for GraphQL");
+    }
+    return {
+        network: "mainnet",
+        expectedChainIdentifier: SUI_MAINNET_CHAIN_IDENTIFIER,
+        reviewHost: "127.0.0.1",
+        reviewPort: parseReviewPort(env.SAY_UR_INTENT_REVIEW_PORT),
+        activityDatabasePath: resolveActivityDatabasePath(env)
+    };
+}
+// Fixed default so the loopback review origin (scheme://127.0.0.1:port) stays
+// stable across server restarts, which is what lets the browser wallet
+// autoconnect silently instead of prompting again. Override per MCP
+// registration with SAY_UR_INTENT_REVIEW_PORT. The port is never silently
+// reassigned to a random port (that would break origin continuity); instead,
+// when a newer instance finds the port held by a previous Say Ur Intent review
+// server on the same machine, it takes the port over so the most recently
+// started client owns the single review origin (see reviewServerAcquire.ts).
+export const DEFAULT_REVIEW_PORT = 8765;
+function parseReviewPort(value) {
+    if (value === undefined || value === "") {
+        return DEFAULT_REVIEW_PORT;
+    }
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`SAY_UR_INTENT_REVIEW_PORT must be an integer between 1 and 65535, got: ${value}`);
+    }
+    return port;
+}
+export function composeRuntimeConfig(input) {
+    const env = input.env ?? process.env;
+    const defaultSuiGrpcUrl = parseGrpcUrl(input.defaultSuiGrpcUrl ?? DEFAULT_SUI_GRPC_URL);
+    const defaultSuiGraphqlUrl = parseGraphqlUrl(input.defaultSuiGraphqlUrl ?? DEFAULT_SUI_GRAPHQL_URL);
+    const storedValue = parseGrpcUrl(input.storedSuiGrpcUrl ?? defaultSuiGrpcUrl);
+    const storedGraphqlValue = parseGraphqlUrl(input.storedSuiGraphqlUrl ?? defaultSuiGraphqlUrl);
+    const envValue = env.SUI_GRPC_URL === undefined ? undefined : parseGrpcUrl(env.SUI_GRPC_URL);
+    const envGraphqlValue = env.SUI_GRAPHQL_URL === undefined ? undefined : parseGraphqlUrl(env.SUI_GRAPHQL_URL);
+    const suiGrpcUrl = resolveSuiGrpcUrlView({
+        defaultSuiGrpcUrl,
+        storedValue,
+        envValue
+    });
+    const suiGraphqlUrl = resolveSuiGraphqlUrlView({
+        defaultSuiGraphqlUrl,
+        storedValue: storedGraphqlValue,
+        envValue: envGraphqlValue
+    });
+    return {
+        ...input.bootConfig,
+        grpcUrl: suiGrpcUrl.effectiveValue,
+        graphqlUrl: suiGraphqlUrl.effectiveValue,
+        suiGrpcUrl,
+        suiGraphqlUrl
+    };
+}
+export function resolveSuiGrpcUrlView(input) {
+    const defaultSuiGrpcUrl = parseGrpcUrl(input.defaultSuiGrpcUrl ?? DEFAULT_SUI_GRPC_URL);
+    const storedValue = parseGrpcUrl(input.storedValue ?? defaultSuiGrpcUrl);
+    if (input.envValue !== undefined) {
+        const effectiveValue = parseGrpcUrl(input.envValue);
+        return {
+            storedValue,
+            effectiveValue,
+            source: "environment",
+            pendingStoredValue: effectiveValue === storedValue ? undefined : storedValue,
+            appliesAfter: effectiveValue === storedValue ? undefined : SETTINGS_APPLIES_AFTER_RESTART
+        };
+    }
+    return {
+        storedValue,
+        effectiveValue: storedValue,
+        source: storedValue === defaultSuiGrpcUrl ? "builtin_default" : "local_db"
+    };
+}
+export function resolveSuiGraphqlUrlView(input) {
+    const defaultSuiGraphqlUrl = parseGraphqlUrl(input.defaultSuiGraphqlUrl ?? DEFAULT_SUI_GRAPHQL_URL);
+    const storedValue = parseGraphqlUrl(input.storedValue ?? defaultSuiGraphqlUrl);
+    if (input.envValue !== undefined) {
+        const effectiveValue = parseGraphqlUrl(input.envValue);
+        return {
+            storedValue,
+            effectiveValue,
+            source: "environment",
+            pendingStoredValue: effectiveValue === storedValue ? undefined : storedValue,
+            appliesAfter: effectiveValue === storedValue ? undefined : SETTINGS_APPLIES_AFTER_RESTART
+        };
+    }
+    return {
+        storedValue,
+        effectiveValue: storedValue,
+        source: storedValue === defaultSuiGraphqlUrl ? "builtin_default" : "local_db"
+    };
+}
+export { DEFAULT_SUI_GRAPHQL_URL, DEFAULT_SUI_GRPC_URL, SUI_MAINNET_CHAIN_IDENTIFIER };

package/dist/runtime/localSettingsService.js

@@ -0,0 +1,198 @@
+import { SETTINGS_APPLIES_AFTER_RESTART, LocalSettingsError } from "../core/preferences/preferencesStore.js";
+import { DEFAULT_SUI_GRAPHQL_ENDPOINT_VERIFY_TIMEOUT_MS, DEFAULT_SUI_GRAPHQL_URL, DEFAULT_SUI_GRPC_ENDPOINT_VERIFY_TIMEOUT_MS, DEFAULT_SUI_GRPC_URL, SUI_MAINNET_CHAIN_IDENTIFIER, SuiEndpointError, parseGraphqlUrl, parseGrpcUrl, verifyMainnetGraphqlEndpoint, verifyMainnetGrpcEndpoint } from "./suiEndpoint.js";
+import { resolveSuiGraphqlUrlView, resolveSuiGrpcUrlView } from "./config.js";
+export class RuntimeLocalSettingsService {
+    options;
+    env;
+    defaultSuiGrpcUrl;
+    defaultSuiGraphqlUrl;
+    bootSuiGrpcUrl;
+    bootSuiGraphqlUrl;
+    verifyGrpcEndpoint;
+    verifyGraphqlEndpoint;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.env = options.env ?? process.env;
+        this.defaultSuiGrpcUrl = parseGrpcUrl(options.defaultSuiGrpcUrl ?? DEFAULT_SUI_GRPC_URL);
+        this.defaultSuiGraphqlUrl = parseGraphqlUrl(options.defaultSuiGraphqlUrl ?? DEFAULT_SUI_GRAPHQL_URL);
+        this.bootSuiGrpcUrl = normalizeBootSuiGrpcUrlView(options.bootSuiGrpcUrl ??
+            resolveSuiGrpcUrlView({
+                defaultSuiGrpcUrl: this.defaultSuiGrpcUrl,
+                envValue: this.env.SUI_GRPC_URL
+            }));
+        this.bootSuiGraphqlUrl = normalizeBootSuiGraphqlUrlView(options.bootSuiGraphqlUrl ??
+            resolveSuiGraphqlUrlView({
+                defaultSuiGraphqlUrl: this.defaultSuiGraphqlUrl,
+                envValue: this.env.SUI_GRAPHQL_URL
+            }));
+        this.verifyGrpcEndpoint = options.verifyGrpcEndpoint ?? defaultGrpcEndpointVerifier;
+        this.verifyGraphqlEndpoint = options.verifyGraphqlEndpoint ?? defaultGraphqlEndpointVerifier;
+        this.now = options.now ?? (() => new Date());
+    }
+    async getLocalSettings() {
+        const stored = await this.options.preferencesRepository.getSuiGrpcUrl();
+        const storedGraphql = await this.options.preferencesRepository.getSuiGraphqlUrl();
+        const currentStoredView = resolveSuiGrpcUrlView({
+            defaultSuiGrpcUrl: this.defaultSuiGrpcUrl,
+            storedValue: stored?.value,
+            envValue: this.env.SUI_GRPC_URL
+        });
+        const currentStoredGraphqlView = resolveSuiGraphqlUrlView({
+            defaultSuiGraphqlUrl: this.defaultSuiGraphqlUrl,
+            storedValue: storedGraphql?.value,
+            envValue: this.env.SUI_GRAPHQL_URL
+        });
+        return {
+            suiGrpcUrl: withBootEffectiveEndpoint(currentStoredView, this.bootSuiGrpcUrl),
+            suiGraphqlUrl: withBootEffectiveEndpoint(currentStoredGraphqlView, this.bootSuiGraphqlUrl)
+        };
+    }
+    async setSuiGrpcUrl(url) {
+        const normalized = parseEndpointForTool(url);
+        await this.verifyEndpointForTool(normalized, "grpc");
+        const result = await this.options.preferencesRepository.setSuiGrpcUrl(normalized, this.now());
+        return {
+            status: "saved",
+            storedValue: result.storedValue,
+            previousStoredValue: result.previousStoredValue,
+            appliesAfter: SETTINGS_APPLIES_AFTER_RESTART
+        };
+    }
+    async setSuiGraphqlUrl(url) {
+        const normalized = parseGraphqlEndpointForTool(url);
+        await this.verifyEndpointForTool(normalized, "graphql");
+        const result = await this.options.preferencesRepository.setSuiGraphqlUrl(normalized, this.now());
+        return {
+            status: "saved",
+            storedValue: result.storedValue,
+            previousStoredValue: result.previousStoredValue,
+            appliesAfter: SETTINGS_APPLIES_AFTER_RESTART
+        };
+    }
+    async resetSuiGrpcUrl() {
+        const result = await this.options.preferencesRepository.resetSuiGrpcUrl(this.defaultSuiGrpcUrl, this.now());
+        return {
+            status: "reset",
+            storedValue: result.storedValue,
+            previousStoredValue: result.previousStoredValue,
+            appliesAfter: SETTINGS_APPLIES_AFTER_RESTART
+        };
+    }
+    async resetSuiGraphqlUrl() {
+        const result = await this.options.preferencesRepository.resetSuiGraphqlUrl(this.defaultSuiGraphqlUrl, this.now());
+        return {
+            status: "reset",
+            storedValue: result.storedValue,
+            previousStoredValue: result.previousStoredValue,
+            appliesAfter: SETTINGS_APPLIES_AFTER_RESTART
+        };
+    }
+    async verifyEndpointForTool(url, transport) {
+        try {
+            await (transport === "grpc" ? this.verifyGrpcEndpoint(url) : this.verifyGraphqlEndpoint(url));
+        }
+        catch (error) {
+            if (error instanceof LocalSettingsError) {
+                throw error;
+            }
+            if (error instanceof SuiEndpointError) {
+                throw endpointErrorForTool(error, transport);
+            }
+            const label = transport === "grpc" ? "gRPC" : "GraphQL";
+            throw new LocalSettingsError("internal_error", `Sui ${label} endpoint verification failed`, {
+                message: `Sui ${label} endpoint verification failed`
+            });
+        }
+    }
+}
+function normalizeBootSuiGrpcUrlView(view) {
+    return {
+        ...view,
+        storedValue: parseGrpcUrl(view.storedValue),
+        effectiveValue: parseGrpcUrl(view.effectiveValue)
+    };
+}
+function normalizeBootSuiGraphqlUrlView(view) {
+    return {
+        ...view,
+        storedValue: parseGraphqlUrl(view.storedValue),
+        effectiveValue: parseGraphqlUrl(view.effectiveValue)
+    };
+}
+function withBootEffectiveEndpoint(storedView, bootView) {
+    if (storedView.effectiveValue === bootView.effectiveValue) {
+        return storedView;
+    }
+    return {
+        storedValue: storedView.storedValue,
+        effectiveValue: bootView.effectiveValue,
+        source: bootView.source,
+        pendingStoredValue: storedView.storedValue === bootView.effectiveValue ? undefined : storedView.storedValue,
+        appliesAfter: SETTINGS_APPLIES_AFTER_RESTART
+    };
+}
+async function defaultGrpcEndpointVerifier(url) {
+    await verifyMainnetGrpcEndpoint({
+        url,
+        expectedChainIdentifier: SUI_MAINNET_CHAIN_IDENTIFIER,
+        timeoutMs: DEFAULT_SUI_GRPC_ENDPOINT_VERIFY_TIMEOUT_MS
+    });
+}
+async function defaultGraphqlEndpointVerifier(url) {
+    await verifyMainnetGraphqlEndpoint({
+        url,
+        expectedChainIdentifier: SUI_MAINNET_CHAIN_IDENTIFIER,
+        timeoutMs: DEFAULT_SUI_GRAPHQL_ENDPOINT_VERIFY_TIMEOUT_MS
+    });
+}
+function parseEndpointForTool(url) {
+    try {
+        return parseGrpcUrl(url);
+    }
+    catch (error) {
+        if (error instanceof SuiEndpointError) {
+            throw endpointErrorForTool(error, "grpc");
+        }
+        throw error;
+    }
+}
+function parseGraphqlEndpointForTool(url) {
+    try {
+        return parseGraphqlUrl(url);
+    }
+    catch (error) {
+        if (error instanceof SuiEndpointError) {
+            throw endpointErrorForTool(error, "graphql");
+        }
+        throw error;
+    }
+}
+function endpointErrorForTool(error, transport) {
+    const label = transport === "grpc" ? "gRPC" : "GraphQL";
+    if (error.kind === "chain_identifier_mismatch") {
+        return new LocalSettingsError("input_invalid", `Sui ${label} endpoint did not report the mainnet chain identifier`, {
+            reason: error.kind,
+            ...endpointErrorDetailsForTool(error, ["chainIdentifier", "expectedChainIdentifier"])
+        });
+    }
+    if (error.kind === "endpoint_timeout" || error.kind === "endpoint_unreachable") {
+        return new LocalSettingsError("input_invalid", `Sui ${label} endpoint could not be verified`, {
+            reason: error.kind,
+            ...endpointErrorDetailsForTool(error, error.kind === "endpoint_timeout" ? ["timeoutMs"] : [])
+        });
+    }
+    return new LocalSettingsError("input_invalid", error.message, {
+        reason: error.kind
+    });
+}
+function endpointErrorDetailsForTool(error, allowedKeys) {
+    const details = {};
+    for (const key of allowedKeys) {
+        const value = error.details[key];
+        if (value !== undefined) {
+            details[key] = value;
+        }
+    }
+    return details;
+}

package/dist/runtime/logger.js

@@ -0,0 +1,50 @@
+export function createStderrLogger(scope) {
+    const write = (level, message, meta) => {
+        const record = {
+            level,
+            scope,
+            message,
+            meta: meta ? redactMeta(meta) : undefined,
+            at: new Date().toISOString()
+        };
+        process.stderr.write(`${JSON.stringify(record)}\n`);
+    };
+    return {
+        info: (message, meta) => write("info", message, meta),
+        warn: (message, meta) => write("warn", message, meta),
+        error: (message, meta) => write("error", message, meta)
+    };
+}
+const REDACTED = "[redacted]";
+const CIRCULAR = "[circular]";
+const SENSITIVE_META_KEY = /token|secret|private|signature|bytes/i;
+export function redactMeta(meta) {
+    return redactRecord(meta, new WeakSet());
+}
+function redactRecord(record, seen) {
+    if (seen.has(record)) {
+        return { value: CIRCULAR };
+    }
+    seen.add(record);
+    const redacted = Object.fromEntries(Object.entries(record).map(([key, value]) => [
+        key,
+        SENSITIVE_META_KEY.test(key) ? REDACTED : redactValue(value, seen)
+    ]));
+    seen.delete(record);
+    return redacted;
+}
+function redactValue(value, seen) {
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value)) {
+            return CIRCULAR;
+        }
+        seen.add(value);
+        const redacted = value.map((item) => redactValue(item, seen));
+        seen.delete(value);
+        return redacted;
+    }
+    return redactRecord(value, seen);
+}

package/dist/runtime/reviewServerAcquire.js

@@ -0,0 +1,128 @@
+function errorCode(error) {
+    return typeof error === "object" && error !== null
+        ? error.code
+        : undefined;
+}
+/**
+ * Bind the review server to its fixed port, taking the port over from a previous
+ * instance of our own review server if necessary.
+ *
+ * Safety: the holder is positively identified over loopback before any signal is
+ * sent. A process that is not our review server is never signalled; a same-name
+ * instance owned by another OS user surfaces a clear error rather than a kill.
+ * The port is never silently reassigned, so the wallet autoconnect origin stays
+ * stable.
+ */
+export async function startReviewServerWithTakeover(start, port, deps) {
+    try {
+        return await start(port);
+    }
+    catch (error) {
+        if (errorCode(error) !== "EADDRINUSE") {
+            throw error;
+        }
+        const holder = await deps.probeIdentity(port);
+        if (!holder || holder.service !== deps.serviceName) {
+            throw new Error(`Review server port ${port} is already in use by a process that is not a ${deps.serviceName} review server. ` +
+                `Set SAY_UR_INTENT_REVIEW_PORT to a free port. The port is not reassigned automatically so the wallet autoconnect origin stays stable.`);
+        }
+        if (holder.pid === deps.currentPid) {
+            // We appear to hold the port ourselves yet cannot bind it. Never signal
+            // our own process; surface the original bind error.
+            throw error;
+        }
+        deps.logger.info("review port held by a previous say-ur-intent instance; taking it over", {
+            port,
+            previousPid: holder.pid
+        });
+        const terminated = deps.terminate(holder.pid);
+        if (!terminated.ok) {
+            if (terminated.reason === "no_permission") {
+                throw new Error(`Review server port ${port} is held by a ${deps.serviceName} instance owned by another OS user; cannot take it over. ` +
+                    `Set SAY_UR_INTENT_REVIEW_PORT to a free port for this client.`);
+            }
+            if (terminated.reason === "error") {
+                throw new Error(`Failed to stop the ${deps.serviceName} instance holding review port ${port}: ${terminated.message ?? "unknown error"}.`);
+            }
+            // not_found: the holder already exited between probe and signal; fall
+            // through and rebind.
+        }
+        const waitForReleaseMs = deps.waitForReleaseMs ?? 3000;
+        const pollIntervalMs = deps.pollIntervalMs ?? 100;
+        const attempts = Math.max(1, Math.ceil(waitForReleaseMs / pollIntervalMs));
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            await deps.delay(pollIntervalMs);
+            try {
+                return await start(port);
+            }
+            catch (retryError) {
+                if (errorCode(retryError) !== "EADDRINUSE") {
+                    throw retryError;
+                }
+            }
+        }
+        throw new Error(`Review server port ${port} did not become free after stopping the previous ${deps.serviceName} instance (pid ${holder.pid}). ` +
+            `Set SAY_UR_INTENT_REVIEW_PORT to a free port.`);
+    }
+}
+/**
+ * Ask whatever is listening on the loopback review port to identify itself. Only
+ * our own review server answers `/__identity`; any other process either returns
+ * something else or does not answer, and we report it as "not ours" so the
+ * caller never signals it.
+ */
+export async function probeReviewServerIdentity(port, host = "127.0.0.1", timeoutMs = 1000) {
+    try {
+        const response = await fetch(`http://${host}:${port}/__identity`, {
+            method: "GET",
+            signal: AbortSignal.timeout(timeoutMs)
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const body = await response.json();
+        if (typeof body === "object" &&
+            body !== null &&
+            typeof body.service === "string" &&
+            typeof body.role === "string" &&
+            typeof body.pid === "number") {
+            const typed = body;
+            return {
+                service: typed.service,
+                role: typed.role,
+                pid: typed.pid,
+                ...(typeof typed.version === "string" ? { version: typed.version } : {})
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Gracefully signal a same-user process. SIGTERM lets the previous instance run
+ * its own shutdown handler (close the review server and database, then exit).
+ * Killing another OS user's process fails with EPERM, which we report instead of
+ * escalating.
+ */
+export function terminateProcessByPid(pid) {
+    try {
+        process.kill(pid, "SIGTERM");
+        return { ok: true };
+    }
+    catch (error) {
+        const code = errorCode(error);
+        if (code === "ESRCH") {
+            return { ok: false, reason: "not_found" };
+        }
+        if (code === "EPERM") {
+            return { ok: false, reason: "no_permission" };
+        }
+        return {
+            ok: false,
+            reason: "error",
+            message: error instanceof Error ? error.message : String(error)
+        };
+    }
+}