conductor-remote 1.99.0 → 1.101.0

package/dist-node/src/voice/broker.js

@@ -0,0 +1,447 @@
+/** OpenAI SIP/WebRTC setup plus the authenticated sideband controller for one live call. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { VOICE_INSTRUCTIONS } from "./prompt.js";
+import { VOICE_TOOL_NAMES } from "./tools.js";
+/** Current Realtime call-accept shape, kept pure so upstream API drift has a snapshot-sized test. */
+export function buildAcceptBody(input) {
+    return {
+        type: 'realtime',
+        model: input.model,
+        instructions: input.instructions,
+        max_output_tokens: 800,
+        audio: { output: { voice: input.voice } },
+        tools: [
+            {
+                type: 'mcp',
+                server_label: 'conductor_voice',
+                server_url: input.mcpUrl,
+                headers: {
+                    authorization: `Bearer ${input.mcpToken}`,
+                    'x-voice-call-id': input.callId
+                },
+                allowed_tools: [...VOICE_TOOL_NAMES],
+                require_approval: 'never'
+            }
+        ]
+    };
+}
+/** USD estimate for the model whose rates are pinned in the design and documentation. */
+export function estimateRealtimeCost(model, usage) {
+    if (model !== 'gpt-realtime-2.1-mini')
+        return null;
+    const input = usage.input_token_details ?? {};
+    const output = usage.output_token_details ?? {};
+    const cachedText = input.cached_tokens_details?.text_tokens ?? 0;
+    const cachedAudio = input.cached_tokens_details?.audio_tokens ?? 0;
+    const uncachedText = Math.max(0, (input.text_tokens ?? 0) - cachedText);
+    const uncachedAudio = Math.max(0, (input.audio_tokens ?? 0) - cachedAudio);
+    return ((uncachedText * 0.6 +
+        cachedText * 0.06 +
+        uncachedAudio * 10 +
+        cachedAudio * 0.3 +
+        (output.text_tokens ?? 0) * 2.4 +
+        (output.audio_tokens ?? 0) * 20) /
+        1_000_000);
+}
+function defaultSocket(url, headers) {
+    // Node 24's built-in client accepts an undici options object here. DOM's constructor
+    // type still describes the browser's `protocols` argument, hence the narrow cast.
+    const Client = WebSocket;
+    return new Client(url, { headers });
+}
+function messageText(raw) {
+    if (typeof raw === 'string')
+        return raw;
+    if (raw instanceof ArrayBuffer)
+        return Buffer.from(raw).toString('utf8');
+    if (ArrayBuffer.isView(raw))
+        return Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength).toString('utf8');
+    return String(raw ?? '');
+}
+function safeNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+export class VoiceBroker {
+    stateFile;
+    deps;
+    fetcher;
+    sockets;
+    log;
+    now;
+    apiOrigin;
+    websocketOrigin;
+    calls = new Map();
+    runtimes = new Map();
+    constructor(deps) {
+        this.deps = deps;
+        this.stateFile = deps.stateFile;
+        this.fetcher = deps.fetch ?? fetch;
+        this.sockets = deps.socket ?? defaultSocket;
+        this.log = deps.log ?? console.info;
+        this.now = deps.now ?? Date.now;
+        this.apiOrigin = deps.apiOrigin.replace(/\/+$/, '');
+        this.websocketOrigin = this.apiOrigin.replace(/^https:/, 'wss:');
+        this.readCalls();
+    }
+    readCalls() {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.stateFile, 'utf8'));
+            if (!Array.isArray(parsed))
+                return;
+            for (const raw of parsed) {
+                const call = raw;
+                if (typeof call.callId === 'string' && typeof call.acceptedAt === 'number') {
+                    this.calls.set(call.callId, {
+                        callId: call.callId,
+                        acceptedAt: call.acceptedAt,
+                        // Records written before WebRTC support were all SIP/MCP calls.
+                        mode: call.mode === 'function' ? 'function' : 'mcp',
+                        ready: call.ready ?? true,
+                        greeted: call.greeted ?? false
+                    });
+                }
+            }
+        }
+        catch {
+            // First run or a recoverable partial file: the webhook can repopulate it.
+        }
+    }
+    persist() {
+        fs.mkdirSync(path.dirname(this.stateFile), { recursive: true });
+        fs.writeFileSync(this.stateFile, `${JSON.stringify([...this.calls.values()], null, 2)}\n`, { mode: 0o600 });
+        fs.chmodSync(this.stateFile, 0o600);
+    }
+    async accept(callId, options = {}) {
+        if (!this.deps.mcpUrl || !this.deps.mcpToken)
+            throw new Error('SIP voice MCP is not configured');
+        const response = await this.fetcher(`${this.apiOrigin}/v1/realtime/calls/${encodeURIComponent(callId)}/accept`, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${this.deps.apiKey}`, 'content-type': 'application/json' },
+            body: JSON.stringify(buildAcceptBody({
+                callId,
+                model: this.deps.model,
+                voice: options.voice ?? this.deps.voice,
+                mcpUrl: this.deps.mcpUrl,
+                mcpToken: this.deps.mcpToken,
+                instructions: options.instructions ?? this.deps.instructions ?? VOICE_INSTRUCTIONS
+            }))
+        });
+        if (!response.ok)
+            throw new Error(`OpenAI call accept returned ${response.status}: ${await response.text()}`);
+        this.calls.set(callId, {
+            callId,
+            acceptedAt: this.now(),
+            mode: 'mcp',
+            ready: true,
+            greeted: false
+        });
+        this.persist();
+        this.attach(callId);
+    }
+    async reject(callId, statusCode = 603) {
+        const response = await this.fetcher(`${this.apiOrigin}/v1/realtime/calls/${encodeURIComponent(callId)}/reject`, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${this.deps.apiKey}`, 'content-type': 'application/json' },
+            body: JSON.stringify({ status_code: statusCode })
+        });
+        if (!response.ok)
+            throw new Error(`OpenAI call reject returned ${response.status}: ${await response.text()}`);
+    }
+    /** Reattach every call whose socket was alive when a self-update stopped this process. */
+    async restore() {
+        for (const callId of this.calls.keys())
+            this.attach(callId);
+    }
+    attach(callId) {
+        if (this.runtimes.has(callId))
+            return;
+        const call = this.calls.get(callId);
+        if (!call)
+            return;
+        const socket = this.sockets(`${this.websocketOrigin}/v1/realtime?call_id=${encodeURIComponent(callId)}`, {
+            authorization: `Bearer ${this.deps.apiKey}`
+        });
+        const runtime = {
+            socket,
+            mode: call.mode,
+            ready: call.ready,
+            open: socket.readyState === 1,
+            toolsReady: call.mode === 'function',
+            greeted: call.greeted,
+            started: call.greeted,
+            responseActive: false,
+            responseDone: false,
+            responseHadTool: false,
+            pending: [],
+            pendingTools: new Set(),
+            handledTools: new Set(),
+            toolStarted: new Map()
+        };
+        this.runtimes.set(callId, runtime);
+        socket.addEventListener('open', () => {
+            runtime.open = true;
+            this.maybeStart(runtime);
+            this.flush(runtime);
+        });
+        socket.addEventListener('message', event => this.onEvent(callId, runtime, messageText(event.data)));
+        socket.addEventListener('error', () => this.log(`[voice] ${callId} observer socket error`));
+        socket.addEventListener('close', () => {
+            if (this.runtimes.get(callId) !== runtime)
+                return;
+            this.forget(callId, runtime);
+            this.log(`[voice] ${callId} observer closed`);
+        });
+        this.maybeStart(runtime);
+    }
+    send(runtime, value) {
+        if (runtime.socket.readyState !== 1)
+            return;
+        runtime.socket.send(JSON.stringify(value));
+    }
+    forget(callId, runtime) {
+        if (runtime && this.runtimes.get(callId) !== runtime)
+            return;
+        const existed = this.calls.delete(callId);
+        this.runtimes.delete(callId);
+        if (!existed)
+            return;
+        this.persist();
+        this.deps.onClose?.(callId);
+    }
+    createResponse(runtime) {
+        if (runtime.responseActive || runtime.socket.readyState !== 1)
+            return false;
+        runtime.responseActive = true;
+        runtime.responseDone = false;
+        runtime.responseHadTool = false;
+        this.send(runtime, { type: 'response.create' });
+        return true;
+    }
+    maybeStart(runtime) {
+        if (!runtime.open || !runtime.ready || !runtime.toolsReady || runtime.started)
+            return;
+        runtime.started = this.createResponse(runtime);
+    }
+    flush(runtime) {
+        if (!runtime.toolsReady || !runtime.greeted || runtime.responseActive || runtime.socket.readyState !== 1)
+            return;
+        const text = runtime.pending.shift();
+        if (!text)
+            return;
+        this.send(runtime, {
+            type: 'conversation.item.create',
+            item: { type: 'message', role: 'user', content: [{ type: 'input_text', text }] }
+        });
+        this.createResponse(runtime);
+    }
+    /** OpenAI may finish the response before or after its tool calls. Both are a barrier. */
+    continueAfterTools(runtime) {
+        if (!runtime.responseDone || !runtime.responseHadTool || runtime.pendingTools.size)
+            return;
+        runtime.responseDone = false;
+        runtime.responseHadTool = false;
+        this.createResponse(runtime);
+    }
+    finishTool(callId, runtime, event) {
+        const item = (event.item ?? {});
+        const id = typeof event.item_id === 'string' ? event.item_id : typeof item.id === 'string' ? item.id : null;
+        const started = id ? runtime.toolStarted.get(id) : undefined;
+        if (id) {
+            runtime.toolStarted.delete(id);
+            runtime.pendingTools.delete(id);
+        }
+        const name = typeof item.name === 'string' ? item.name : (id ?? 'unknown tool');
+        const latency = started === undefined ? 'unknown latency' : `${this.now() - started}ms`;
+        this.log(`[voice] ${callId} tool ${name}: ${latency}`);
+        runtime.responseHadTool = true;
+        // Remote MCP results do not automatically continue, but OpenAI requires the
+        // original response *and every MCP call in it* to finish before the next one.
+        this.continueAfterTools(runtime);
+    }
+    startFunction(callId, runtime, event) {
+        if (runtime.mode !== 'function')
+            return;
+        const item = (event.item ?? {});
+        const invocationId = typeof event.call_id === 'string' ? event.call_id : typeof item.call_id === 'string' ? item.call_id : null;
+        const name = typeof event.name === 'string' ? event.name : typeof item.name === 'string' ? item.name : null;
+        const encodedArgs = typeof event.arguments === 'string' ? event.arguments : typeof item.arguments === 'string' ? item.arguments : '{}';
+        if (!invocationId || !name || runtime.handledTools.has(invocationId))
+            return;
+        runtime.handledTools.add(invocationId);
+        runtime.pendingTools.add(invocationId);
+        runtime.toolStarted.set(invocationId, this.now());
+        runtime.responseHadTool = true;
+        void (async () => {
+            let output;
+            try {
+                const parsed = JSON.parse(encodedArgs);
+                if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                    throw new Error('tool arguments must be an object');
+                const tool = this.deps.tools?.(callId).find(candidate => candidate.name === name);
+                if (!tool)
+                    throw new Error(`tool ${name} is not available in this call`);
+                output = await tool.run(parsed);
+            }
+            catch (error) {
+                output = JSON.stringify({
+                    status: 'error',
+                    spoken: `The relay could not run that action: ${error instanceof Error ? error.message : String(error)}`
+                });
+            }
+            this.send(runtime, {
+                type: 'conversation.item.create',
+                item: { type: 'function_call_output', call_id: invocationId, output }
+            });
+            const started = runtime.toolStarted.get(invocationId);
+            runtime.toolStarted.delete(invocationId);
+            runtime.pendingTools.delete(invocationId);
+            const latency = started === undefined ? 'unknown latency' : `${this.now() - started}ms`;
+            this.log(`[voice] ${callId} tool ${name}: ${latency}`);
+            this.continueAfterTools(runtime);
+        })();
+    }
+    logUsage(callId, usage) {
+        const input = safeNumber(usage.input_tokens);
+        const output = safeNumber(usage.output_tokens);
+        const detailedInput = safeNumber(usage.input_token_details?.text_tokens) + safeNumber(usage.input_token_details?.audio_tokens);
+        const detailedOutput = safeNumber(usage.output_token_details?.text_tokens) + safeNumber(usage.output_token_details?.audio_tokens);
+        const tokens = safeNumber(usage.total_tokens) || input + output || detailedInput + detailedOutput;
+        const cost = estimateRealtimeCost(this.deps.model, usage);
+        this.log(`[voice] ${callId} ${tokens} tokens${cost === null ? '' : `, estimated $${cost.toFixed(4)}`}`);
+    }
+    onEvent(callId, runtime, raw) {
+        let event;
+        try {
+            event = JSON.parse(raw);
+        }
+        catch {
+            this.log(`[voice] ${callId} sent an unreadable observer event`);
+            return;
+        }
+        const type = event.type;
+        if (type === 'mcp_list_tools.completed') {
+            if (runtime.mode !== 'mcp')
+                return;
+            runtime.toolsReady = true;
+            this.maybeStart(runtime);
+            this.flush(runtime);
+            return;
+        }
+        if (type === 'mcp_list_tools.failed') {
+            this.log(`[voice] ${callId} could not import the scoped voice tools`);
+            return;
+        }
+        if (type === 'response.created') {
+            // Server VAD can start a response without this sideband having sent
+            // `response.create`; broker nudges must not collide with it.
+            runtime.responseActive = true;
+            return;
+        }
+        if (type === 'response.mcp_call.in_progress' && typeof event.item_id === 'string') {
+            runtime.responseHadTool = true;
+            runtime.pendingTools.add(event.item_id);
+            runtime.toolStarted.set(event.item_id, this.now());
+            return;
+        }
+        if (type === 'response.function_call_arguments.done') {
+            this.startFunction(callId, runtime, event);
+            return;
+        }
+        if (type === 'response.output_item.done' && event.item?.type === 'mcp_call') {
+            this.finishTool(callId, runtime, event);
+            return;
+        }
+        if (type === 'response.output_item.done' &&
+            event.item?.type === 'function_call') {
+            this.startFunction(callId, runtime, event);
+            return;
+        }
+        if (type === 'response.mcp_call.failed') {
+            this.finishTool(callId, runtime, event);
+            return;
+        }
+        if (type === 'response.done') {
+            runtime.responseActive = false;
+            runtime.responseDone = true;
+            const response = (event.response ?? {});
+            if (response.usage)
+                this.logUsage(callId, response.usage);
+            for (const item of response.output ?? []) {
+                if (item.type === 'mcp_call')
+                    runtime.responseHadTool = true;
+                if (item.type === 'function_call')
+                    this.startFunction(callId, runtime, { item });
+            }
+            if (runtime.responseHadTool) {
+                this.continueAfterTools(runtime);
+                return;
+            }
+            runtime.responseDone = false;
+            if (!runtime.greeted) {
+                runtime.greeted = true;
+                const call = this.calls.get(callId);
+                if (call) {
+                    call.greeted = true;
+                    this.persist();
+                }
+            }
+            this.flush(runtime);
+        }
+    }
+    /** Attach the relay sideband before the browser receives its SDP answer. */
+    registerWebRtc(callId) {
+        this.calls.set(callId, {
+            callId,
+            acceptedAt: this.now(),
+            mode: 'function',
+            ready: false,
+            greeted: false
+        });
+        this.persist();
+        this.attach(callId);
+    }
+    /** The browser calls this only after it has installed the remote SDP answer. */
+    beginWebRtc(callId) {
+        const call = this.calls.get(callId);
+        if (call?.mode !== 'function')
+            return false;
+        call.ready = true;
+        this.persist();
+        const runtime = this.runtimes.get(callId);
+        if (runtime) {
+            runtime.ready = true;
+            this.maybeStart(runtime);
+        }
+        return true;
+    }
+    /** End only a relay-created browser call; SIP calls remain owned by their phone leg. */
+    async hangupWebRtc(callId) {
+        const call = this.calls.get(callId);
+        if (call?.mode !== 'function')
+            return false;
+        const response = await this.fetcher(`${this.apiOrigin}/v1/realtime/calls/${encodeURIComponent(callId)}/hangup`, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${this.deps.apiKey}` }
+        });
+        const runtime = this.runtimes.get(callId);
+        try {
+            runtime?.socket.close();
+        }
+        finally {
+            this.forget(callId, runtime);
+        }
+        if (!response.ok)
+            throw new Error(`OpenAI call hangup returned ${response.status}: ${await response.text()}`);
+        return true;
+    }
+    /** Queue a broker-authored line; it cannot overtake tool import or the call's greeting. */
+    inject(callId, text) {
+        const runtime = this.runtimes.get(callId);
+        if (!runtime)
+            return false;
+        runtime.pending.push(text);
+        this.flush(runtime);
+        return true;
+    }
+}

package/dist-node/src/voice/config.js

@@ -0,0 +1,171 @@
+/**
+ * The voice layer's own secrets and knobs, in `stateDir()/voice.json` at 0600.
+ *
+ * Separate from the relay's token file for one reason (design ▸ D4): the token that reaches
+ * OpenAI's session store must not be the one that drives this Mac. The relay token is full
+ * remote control; this one reaches `createVoiceTools` and nothing else. They are different
+ * secrets in different files so that no future refactor can quietly make them the same.
+ *
+ * Not `settings.json`, which `/api/settings` serves to the phone. Not the LaunchAgent plist,
+ * which is user-readable and which `scripts/service.ts` already keeps the relay token out of.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { stateDir } from "../config.js";
+/** The listener's loopback port. Non-secret, so it may ride the plist like its siblings. */
+export function voicePort() {
+    const raw = Number(process.env.VOICE_PORT);
+    return Number.isInteger(raw) && raw > 0 && raw <= 65535 ? raw : 8788;
+}
+export function voiceConfigPath() {
+    return path.join(stateDir(), 'voice.json');
+}
+const EMPTY = {
+    webhookSecret: null,
+    openaiKey: null,
+    twilioAuthToken: null,
+    allowedCallers: [],
+    pin: null,
+    projectId: null,
+    publicBaseUrl: null,
+    model: 'gpt-realtime-2.1-mini',
+    voice: 'marin',
+    sipHost: 'sip.api.openai.com'
+};
+export function openAIOriginForSipHost(sipHost) {
+    switch (sipHost) {
+        case 'sip.api.openai.com':
+            return 'https://api.openai.com';
+        case 'sip-eu.api.openai.com':
+            return 'https://eu.api.openai.com';
+        default:
+            throw new Error('voice.sip-host must be sip.api.openai.com or sip-eu.api.openai.com');
+    }
+}
+function asStringOrNull(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function normalizedPublicUrl(value) {
+    if (!value)
+        return null;
+    const trimmed = value.replace(/\/+$/, '');
+    return trimmed.endsWith('/voice') ? trimmed : `${trimmed}/voice`;
+}
+/**
+ * Read the file, minting the scoped token on first use. A malformed file is treated as an empty
+ * one rather than thrown: the listener refusing to start is a worse failure than a re-mint, and
+ * every secret in here is re-enterable while a lost token only costs one dashboard edit.
+ */
+export function readVoiceConfig(file = voiceConfigPath()) {
+    let raw = {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (parsed && typeof parsed === 'object')
+            raw = parsed;
+    }
+    catch {
+        // absent or unreadable — fall through to defaults and mint below
+    }
+    const config = {
+        ...EMPTY,
+        mcpToken: asStringOrNull(raw.mcpToken) ?? crypto.randomBytes(16).toString('hex'),
+        trunkSecret: asStringOrNull(raw.trunkSecret) ?? crypto.randomBytes(32).toString('hex'),
+        webhookSecret: asStringOrNull(raw.webhookSecret),
+        openaiKey: asStringOrNull(raw.openaiKey),
+        twilioAuthToken: asStringOrNull(raw.twilioAuthToken),
+        allowedCallers: Array.isArray(raw.allowedCallers)
+            ? raw.allowedCallers.filter((c) => typeof c === 'string' && Boolean(c.trim())).map(c => c.trim())
+            : [],
+        pin: asStringOrNull(raw.pin),
+        projectId: asStringOrNull(raw.projectId),
+        publicBaseUrl: normalizedPublicUrl(asStringOrNull(raw.publicBaseUrl)),
+        model: asStringOrNull(raw.model) ?? EMPTY.model,
+        voice: asStringOrNull(raw.voice) ?? EMPTY.voice,
+        sipHost: asStringOrNull(raw.sipHost) ?? EMPTY.sipHost
+    };
+    if (asStringOrNull(raw.mcpToken) !== config.mcpToken || asStringOrNull(raw.trunkSecret) !== config.trunkSecret)
+        writeVoiceConfig(config, file);
+    return config;
+}
+/** Write 0600, creating the directory. The mode is set explicitly on an existing file too. */
+export function writeVoiceConfig(config, file = voiceConfigPath()) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    try {
+        fs.chmodSync(file, 0o600);
+    }
+    catch {
+        // a file we just wrote; if the mode cannot be set the write above already failed loudly
+    }
+}
+export const VOICE_SETTING_NAMES = [
+    'voice.openai-key',
+    'voice.webhook-secret',
+    'voice.twilio-auth-token',
+    'voice.allowed-callers',
+    'voice.pin',
+    'voice.project-id',
+    'voice.public-url',
+    'voice.model',
+    'voice.voice',
+    'voice.sip-host'
+];
+/** Apply one CLI setting without ever returning or printing the secret value. `unset` clears nullable fields. */
+export function setVoiceSetting(name, value, file = voiceConfigPath()) {
+    if (!VOICE_SETTING_NAMES.includes(name))
+        throw new Error(`unknown voice setting "${name}"`);
+    const config = readVoiceConfig(file);
+    const nullable = value === 'unset' ? null : value.trim() || null;
+    switch (name) {
+        case 'voice.openai-key':
+            config.openaiKey = nullable;
+            break;
+        case 'voice.webhook-secret':
+            config.webhookSecret = nullable;
+            break;
+        case 'voice.twilio-auth-token':
+            config.twilioAuthToken = nullable;
+            break;
+        case 'voice.allowed-callers':
+            config.allowedCallers =
+                value === 'unset'
+                    ? []
+                    : value
+                        .split(',')
+                        .map(item => item.trim())
+                        .filter(Boolean);
+            break;
+        case 'voice.pin':
+            if (nullable && !/^\d{4,12}$/.test(nullable))
+                throw new Error('voice.pin must be 4–12 digits or unset');
+            config.pin = nullable;
+            break;
+        case 'voice.project-id':
+            config.projectId = nullable;
+            break;
+        case 'voice.public-url':
+            if (nullable && !/^https:\/\/[^/]+(?:\/voice)?\/?$/.test(nullable))
+                throw new Error('voice.public-url must be an HTTPS origin optionally ending in /voice, or unset');
+            config.publicBaseUrl = normalizedPublicUrl(nullable);
+            break;
+        case 'voice.model':
+            if (!nullable)
+                throw new Error('voice.model cannot be unset');
+            config.model = nullable;
+            break;
+        case 'voice.voice':
+            if (!nullable)
+                throw new Error('voice.voice cannot be unset');
+            config.voice = nullable;
+            break;
+        case 'voice.sip-host':
+            if (!nullable)
+                throw new Error('voice.sip-host cannot be unset');
+            openAIOriginForSipHost(nullable);
+            config.sipHost = nullable;
+            break;
+    }
+    writeVoiceConfig(config, file);
+    return config;
+}

package/dist-node/src/voice/funnel.js

@@ -0,0 +1,75 @@
+/** Ownership receipt and pure inspection for the one public `/voice` Funnel mount. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { stateDir } from "../config.js";
+export const VOICE_FUNNEL_PORT = 443;
+export const VOICE_FUNNEL_PATH = '/voice';
+export function voiceFunnelReceiptPath() {
+    return path.join(stateDir(), 'voice-funnel.json');
+}
+export function readVoiceFunnelReceipt(file = voiceFunnelReceiptPath()) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return raw.version === 1 && typeof raw.host === 'string' && raw.path === '/voice' && typeof raw.target === 'string'
+            ? raw
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeVoiceFunnelReceipt(receipt, file = voiceFunnelReceiptPath()) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(file, 0o600);
+}
+function portOf(hostPort) {
+    const port = Number(hostPort.slice(hostPort.lastIndexOf(':') + 1));
+    return Number.isInteger(port) ? port : null;
+}
+function hostOf(hostPort) {
+    return hostPort.slice(0, hostPort.lastIndexOf(':'));
+}
+function proxyMatches(proxy, port) {
+    return proxy === `http://127.0.0.1:${port}` || proxy === `http://localhost:${port}`;
+}
+/**
+ * Decide whether a live path is ours before the service script mutates anything. A matching
+ * target without a receipt is deliberately *not* adopted: it may be the user's manual mount.
+ */
+export function inspectVoiceFunnel(status, voicePort, relayPort, receipt) {
+    let present = false;
+    let targetMatches = false;
+    let owned = false;
+    let funnelOn = false;
+    let relayAtRoot = false;
+    const conflicts = [];
+    for (const [key, web] of Object.entries(status.Web ?? {})) {
+        if (portOf(key) !== VOICE_FUNNEL_PORT)
+            continue;
+        for (const [mount, handler] of Object.entries(web.Handlers ?? {})) {
+            if (mount === '/' && proxyMatches(handler.Proxy, relayPort)) {
+                relayAtRoot = true;
+                continue;
+            }
+            if (mount === VOICE_FUNNEL_PATH && handler.Proxy) {
+                present = true;
+                targetMatches ||= proxyMatches(handler.Proxy, voicePort);
+                const target = handler.Proxy;
+                owned = Boolean(receipt && receipt.host === hostOf(key) && receipt.path === VOICE_FUNNEL_PATH && receipt.target === target);
+                funnelOn ||= status.AllowFunnel?.[key] === true;
+                if (!proxyMatches(handler.Proxy, voicePort) && !owned)
+                    conflicts.push(`${mount} → ${target}`);
+                continue;
+            }
+            conflicts.push(`${mount} → ${handler.Proxy ?? handler.Path ?? (handler.Text !== undefined ? 'text' : 'unknown')}`);
+        }
+    }
+    for (const [key, tcp] of Object.entries(status.TCP ?? {})) {
+        if (portOf(key) === VOICE_FUNNEL_PORT && tcp.TCPForward)
+            conflicts.push(`tcp → ${tcp.TCPForward}`);
+    }
+    if (present && !owned && !conflicts.some(value => value.startsWith(`${VOICE_FUNNEL_PATH} →`)))
+        conflicts.push(`${VOICE_FUNNEL_PATH} → an unowned matching target`);
+    return { present, targetMatches, owned, funnelOn, relayAtRoot, conflicts };
+}