@sidevoice/uplink 0.4.0 → 0.4.2

package/connector.mjs

@@ -9,6 +9,10 @@ import { mkdirSync, openSync, closeSync, writeFileSync, readFileSync, unlinkSync
 import { randomUUID } from 'node:crypto';
 import { capabilityState, SUPPORTED, voiceEnvelope } from './harness-contract.mjs';
 import { harnessFor } from './harnesses.mjs';
+import { privateNetwork } from './pair.mjs';
+import { fileURLToPath } from 'node:url';
+
+const VERSION = JSON.parse(readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf8')).version;
 
 export const PROTOCOL = 1;
 const dataDir = process.env.SIDEVOICE_DATA_DIR || path.join(os.homedir(), '.sidevoice');
@@ -27,8 +31,7 @@ function credentials() {
   const token = process.env.SIDEVOICE_CONNECTOR_TOKEN || saved.token;
   if (!url || !connector_id || !token) throw new Error(`Not paired with any room (looked in ${credentialsPath}): the conversation's voice_pair, or sidevoice pair <room-url> <code>, with the code the room shows`);
   const parsed = new URL(url);
-  const loopback = ['127.0.0.1', 'localhost', '::1'].includes(parsed.hostname);
-  if (parsed.protocol !== 'wss:' && !loopback) throw new Error('The room URL must be wss:// unless it is loopback');
+  if (parsed.protocol !== 'wss:' && !privateNetwork(parsed.hostname)) throw new Error('The room URL must be wss:// unless it stays on this machine or inside its cluster');
   const room = new URL(url); room.protocol = room.protocol === 'wss:' ? 'https:' : 'http:';
   return { url, connector_id, token, room: room.origin };
 }
@@ -219,7 +222,7 @@ async function receive(frame) {
 }
 
 function snapshot() {
-  return { host: hostId, room: creds.room, connected, protocol: PROTOCOL, outbox: outbox.length, room_error: lastError, closed_by_room: [...closedByRoom.keys()],
+  return { host: hostId, version: VERSION, room: creds.room, connected, protocol: PROTOCOL, outbox: outbox.length, room_error: lastError, closed_by_room: [...closedByRoom.keys()],
     bindings: [...bindings.values()].map(({ binding_id, client_ref, harness, thread, title, delivery, capabilities }) =>
       ({ binding_id, client_ref, harness, thread, title, delivery: delivery.kind, capabilities })) };
 }

package/install.mjs

@@ -10,7 +10,8 @@
  *  What it does not do is decide for the person: it never edits a machine-wide Codex configuration it
  *  does not own, and it never relaxes Claude Code's inbound safeguard — those it prints, with the reason. */
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -19,13 +20,66 @@ import { install as installSkill, skillsDir } from './skill.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(path.join(here, 'package.json'), 'utf8')).version;
-/** What a harness should run to start the server. From a checkout it names this copy, so a machine that
- *  installed from source keeps working when the published version moves; otherwise the pinned package. */
+/** The files that make up this package, copied as they are. */
+const PACKAGE_FILES = JSON.parse(readFileSync(path.join(here, 'package.json'), 'utf8')).files.concat('package.json');
+
+function fromSource(env) {
+  if (env.SIDEVOICE_INSTALL_FROM_SOURCE === '0') return false;
+  return env.SIDEVOICE_INSTALL_FROM_SOURCE === '1' || existsSync(path.join(here, '..', '..', '.git'));
+}
+
+/** Where installed copies live: one directory per version, under the XDG data home. */
+export function copiesDir(env = process.env) {
+  return path.join(env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share'), 'sidevoice');
+}
+
+/** What a harness should run to start the server. From a checkout it names that checkout, so a machine that
+ *  installed from source keeps working when the published version moves. Otherwise it names a copy of this
+ *  package that install placed on disk — never `npx`: a session start is not the moment to resolve a package
+ *  (a cold cache, a bin whose name differs from the package's, a 30 s startup budget; one session found no
+ *  `sidevoice` binary at all, 2026-09-21). */
 export function serverCommand(env = process.env) {
-  const fromSource = env.SIDEVOICE_INSTALL_FROM_SOURCE === '1' || existsSync(path.join(here, '..', '..', '.git'));
-  return fromSource
-    ? { command: 'node', args: [path.join(here, 'cli.mjs'), 'mcp'] }
-    : { command: 'npx', args: ['-y', `@sidevoice/uplink@${VERSION}`, 'mcp'] };
+  const cli = fromSource(env) ? path.join(here, 'cli.mjs') : path.join(copiesDir(env), VERSION, 'cli.mjs');
+  return { command: 'node', args: [cli, 'mcp'] };
+}
+
+/** Put this version's files where serverCommand points, and drop the other versions: an installed copy is
+ *  disposable and there is one current one. From a checkout nothing is copied. */
+export function materialize(env = process.env) {
+  if (fromSource(env)) return { action: 'checkout', target: here };
+  const root = copiesDir(env), target = path.join(root, VERSION);
+  mkdirSync(target, { recursive: true });
+  for (const file of PACKAGE_FILES) {
+    const source = path.join(here, file);
+    if (existsSync(source)) cpSync(source, path.join(target, file), { recursive: true });
+  }
+  const removed = [];
+  for (const name of readdirSync(root)) {
+    if (name !== VERSION) { rmSync(path.join(root, name), { recursive: true, force: true }); removed.push(name); }
+  }
+  return { action: 'copied', target, removed };
+}
+
+/** The connector that holds this machine's socket, if any, and which version it is: a façade uses whatever
+ *  connector is running, so one left over from before an upgrade serves every new session with old code. */
+export function runningConnector(env = process.env) {
+  const dataDir = env.SIDEVOICE_DATA_DIR || path.join(os.homedir(), '.sidevoice');
+  const socketPath = env.SIDEVOICE_CONNECTOR_SOCKET || path.join(dataDir, 'connector.sock');
+  let pid = null;
+  try { pid = Number(readFileSync(socketPath + '.lock', 'utf8')) || null; } catch { return null; }
+  return new Promise(resolve => {
+    const socket = net.createConnection(socketPath);
+    const done = value => { clearTimeout(timer); socket.destroy(); resolve(value); };
+    const timer = setTimeout(() => done(null), 1500);
+    let buffer = '';
+    socket.on('error', () => done(null));
+    socket.on('connect', () => socket.write(JSON.stringify({ id: 1, method: 'status', params: {} }) + '\n'));
+    socket.on('data', chunk => {
+      buffer += chunk; const index = buffer.indexOf('\n'); if (index < 0) return;
+      try { const reply = JSON.parse(buffer.slice(0, index)); done({ pid, version: reply.result?.version || null, bindings: reply.result?.bindings?.length ?? null }); }
+      catch { done({ pid, version: null, bindings: null }); }
+    });
+  });
 }
 
 export function flag(argv, name) {
@@ -117,6 +171,8 @@ export async function install(argv = process.argv.slice(2), env = process.env) {
   const done = [], next = [];
 
   done.push(`Sidevoice ${VERSION}.`);
+  const copy = materialize(env);
+  if (copy.action === 'copied') done.push(`Copied this version to ${copy.target}${copy.removed.length ? ` (removed: ${copy.removed.join(', ')})` : ''}.`);
   if (harnesses.includes('claude')) {
     registerWithClaude(done, env);
     const outcome = installSkill(skillsDir([], env));
@@ -126,6 +182,11 @@ export async function install(argv = process.argv.slice(2), env = process.env) {
   const paired = pairedRoom(env);
   done.push(paired ? `This machine is paired with ${paired.origin} (connector ${paired.connector_id}).`
                    : 'This machine is not paired with any room yet.');
+  const running = await runningConnector(env);
+  if (running && running.version !== VERSION) {
+    next.push(`A connector from ${running.version ? 'version ' + running.version : 'an older version'} is still running (pid ${running.pid}) and every conversation on this machine uses it. ` +
+              `It exits by itself 15 s after the last conversation leaves it; to switch now: kill ${running.pid}, then join again from each conversation.`);
+  }
 
   if (harnesses.includes('claude')) {
     next.push('In a conversation, run /voice-room to join the room.' +

package/mcp.mjs

@@ -10,6 +10,9 @@ import { fileURLToPath } from 'node:url';
 import { advertisedCapabilities, capabilityState, SUPPORTED } from './harness-contract.mjs';
 import { harnessFor, identifyHarness } from './harnesses.mjs';
 import { pair, pairedRoom } from './pair.mjs';
+import { readFileSync } from 'node:fs';
+
+const VERSION = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version;
 
 const dataDir = process.env.SIDEVOICE_DATA_DIR || path.join(os.homedir(), '.sidevoice');
 const socketPath = process.env.SIDEVOICE_CONNECTOR_SOCKET || path.join(dataDir, 'connector.sock');
@@ -91,6 +94,11 @@ function pairingNeeded(room, paired) {
   if (target && target !== paired.origin) return `This machine is paired with ${paired.origin}, not ${target}. One room per machine: to switch, ask the user for the pairing code that ${target} shows under "Emparejar conector" and call voice_pair (it replaces the current pairing); to stay, call voice_connect without a room.`;
   return null;
 }
+/** A connector from another version serves this conversation with that version's behaviour. */
+function versionNote(connectorVersion) {
+  if (!ipc || connectorVersion === VERSION) return {};
+  return { note: `The connector running on this machine is ${connectorVersion ? 'version ' + connectorVersion : 'older than this server'}; this conversation runs ${VERSION}. It exits 15 s after the last conversation leaves it; until then behaviour is that version's.` };
+}
 function inboundFor(harness, thread) {
   return capabilityState(harness, 'inspectInbound') === SUPPORTED ? harness.inspectInbound(thread) : null;
 }
@@ -103,6 +111,7 @@ async function invoke(name, args, meta) {
     const module = binding ? harnessFor(binding.harness) : null;
     const inbound = binding ? inboundFor(module, binding.client_ref) : null;
     return { joined: !!binding, room: status.room || pairedRoom()?.origin || null, room_reachable: status.connected, room_error: status.room_error || null,
+             version: VERSION, connector_version: status.version || null, ...versionNote(status.version),
              binding_id: binding?.binding_id || null, harness: binding?.harness || null,
              capabilities: binding?.capabilities || null, inbound,
              ...(closed ? { closed_by_room: true, note: 'The user closed this conversation\'s voice channel from the room. Continue in writing; call voice_connect again only if they ask for voice.' } : {}) };
@@ -141,8 +150,10 @@ async function invoke(name, args, meta) {
     const result = await rpc('register', { client_ref: who.thread, harness: who.harness, thread: who.thread,
       title, delivery: who.delivery, inbound, capabilities, engine });
     binding = { ...result, harness: who.harness, client_ref: who.thread, capabilities };
+    let connectorVersion = null; try { connectorVersion = (await rpc('status', {})).version || null; } catch {}
     return { status: result.pending ? 'joining' : 'joined', harness: who.harness, conversation: who.thread,
-             binding_id: result.binding_id, delivery: 'push', room_reachable: result.connected, capabilities, inbound };
+             binding_id: result.binding_id, delivery: 'push', room_reachable: result.connected, capabilities, inbound,
+             version: VERSION, connector_version: connectorVersion, ...versionNote(connectorVersion) };
   }
   if (!binding) throw new Error('Not connected to the voice room: call voice_connect first (only if the user asked).');
 
@@ -175,7 +186,7 @@ process.stdin.on('data', async chunk => {
     if (request.id === undefined) continue; // notifications need no answer
     let result, error;
     try {
-      if (request.method === 'initialize') result = { protocolVersion: request.params?.protocolVersion || '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'sidevoice', version: '0.2.0' }, instructions: INSTRUCTIONS };
+      if (request.method === 'initialize') result = { protocolVersion: request.params?.protocolVersion || '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'sidevoice', version: VERSION }, instructions: INSTRUCTIONS };
       else if (request.method === 'tools/list') result = { tools };
       else if (request.method === 'tools/call') { const value = await invoke(request.params.name, request.params.arguments || {}, request.params._meta); result = { content: [{ type: 'text', text: JSON.stringify(value) }] }; }
       else if (request.method === 'ping') result = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sidevoice/uplink",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Sidevoice client side: the stdio MCP server your agent uses, one outbound uplink per machine to the room, one-time pairing.",
   "type": "module",
   "license": "MIT",

package/pair.mjs

@@ -12,6 +12,15 @@ export function dataDir(env = process.env) {
   return env.SIDEVOICE_DATA_DIR || path.join(os.homedir(), '.sidevoice');
 }
 
+/** Where a plaintext connection is acceptable: the token must never cross a network we do not own. Loopback,
+ *  and a Kubernetes service name (`<svc>.<ns>.svc`, `<svc>.<ns>.svc.<cluster domain>`), which by construction
+ *  resolves only inside the cluster and is routed there. Anything else — a private IP included — needs TLS: a
+ *  host we cannot classify is not a reason to send a credential in clear. */
+export function privateNetwork(hostname) {
+  if (['127.0.0.1', 'localhost', '::1', '[::1]'].includes(hostname)) return true;
+  return /^[a-z0-9-]+\.[a-z0-9-]+\.svc(\.[a-z0-9.-]+)?$/i.test(hostname);
+}
+
 /** The room's http(s) origin from the socket address the credential stores. */
 export function roomOrigin(wsUrl) {
   const url = new URL(wsUrl); url.protocol = url.protocol === 'wss:' ? 'https:' : 'http:'; return url.origin;
@@ -29,6 +38,9 @@ export function pairedRoom(env = process.env) {
 /** Redeem a code for this host's credential. Returns where it was written. */
 export async function pair(room, code, env = process.env) {
   const base = new URL(room);
+  if (base.protocol !== 'https:' && !privateNetwork(base.hostname)) {
+    throw new Error(`${base.origin} is reached in clear over a network this machine does not own; the room must be https:// there (loopback and Kubernetes service names are the exceptions).`);
+  }
   const response = await fetch(new URL('/api/connectors/pair', base), {
     method: 'POST', headers: { 'content-type': 'application/json' },
     body: JSON.stringify({ code, host: os.hostname() }), signal: AbortSignal.timeout(15_000),