@sidevoice/uplink 0.2.0

package/README.md

@@ -0,0 +1,29 @@
+# Sidevoice uplink — the client side (`@sidevoice/uplink`)
+
+The client side. Three entry points behind one bin (`sidevoice`):
+
+- `mcp` — the stdio MCP server a harness starts. One per conversation. Exposes
+  `voice_connect`, `voice_say`, `voice_disconnect`, `voice_status`; carries the
+  operational instructions in its `initialize` result. It never talks to the
+  room: it keeps one local connection to the connector for as long as the
+  session lives, and the binding it registered dies with that connection.
+- `connector` — one per machine, started by the first façade that needs it and
+  gone fifteen seconds after the last binding leaves. Holds the outbound
+  WebSocket to the room, re-announces its bindings after a reconnect, keeps a
+  durable outbox for speech published while offline, answers the room's
+  heartbeat, and delivers one input event at a time per binding through the
+  adapter that binding was registered with. A file lock makes it a singleton.
+- `pair` — redeems a pairing code from the room UI for this machine's
+  credential (`~/.sidevoice/credentials.json`, mode 0600).
+
+Adapters (`adapters.mjs`): `claude-uds` writes the voice envelope as a user
+message to the Claude Code session's inbox socket; `codex-queue` runs
+`codex queue --thread <id>`; `http` posts to any local receiver that accepts the
+room's message shape (for harnesses that have neither).
+
+Protocol (newline-free JSON over the WebSocket): `connector.hello` ->
+`connector.welcome`; `binding.register` -> `binding.registered|rejected`;
+`binding.unregister`; `input.deliver` -> `input.ack`; `speech.publish` ->
+`speech.published`; `heartbeat` <-> `heartbeat.ack`. Protocol version 1.
+
+Node 22+, no dependencies. Tests: `node --test test/test_connector.mjs`.

package/adapters.mjs

@@ -0,0 +1,69 @@
+/** The last mile, one function per harness. Each takes a binding's delivery target and a room event. */
+import net from 'node:net';
+import { execFile } from 'node:child_process';
+
+/** The header the skill expects before the user's literal words. */
+export function envelope(event) {
+  const header = { channel: event.channel === 'room-control' ? 'room-control' : 'voice',
+    session_id: event.session_id, revision: event.revision, message_id: event.message_id };
+  return JSON.stringify(header) + '\n\n' + event.text;
+}
+
+/** Claude Code: the session's own inbox socket, inherited by the façade that registered the binding.
+ *  The inbox sends no acknowledgement, so this can never report more than what the wire showed:
+ *  the peer hanging up right after the frames is the one observable sign of a refusal. */
+function deliverClaude(delivery, event) {
+  return new Promise((resolve, reject) => {
+    const started = Date.now();
+    const socket = net.createConnection(delivery.socket);
+    let settled = false, wrote = 0, replied = '';
+    const finish = (error, status, detail) => {
+      if (settled) return;
+      settled = true; clearTimeout(timer); socket.destroy();
+      if (error) return reject(error);
+      resolve({ status, detail: `${detail} after ${Date.now() - started}ms${replied ? ', peer said ' + replied.slice(0, 120) : ''}` });
+    };
+    const timer = setTimeout(() => finish(null, 'unknown', 'connection still open, no acknowledgement'), 1500);
+    socket.on('error', error => finish(error));
+    socket.on('data', chunk => { replied += chunk; });
+    socket.on('connect', () => {
+      socket.write(JSON.stringify({ type: 'auth', token: delivery.token }) + '\n');
+      socket.write(JSON.stringify({ type: 'user', message: { role: 'user', content: envelope(event) } }) + '\n');
+      wrote = Date.now();
+    });
+    // A hang-up right after the frames is how a refused auth or a closed inbox looks from here.
+    socket.on('close', () => finish(null, 'rejected', wrote ? 'peer closed the connection' : 'peer closed before the frames were written'));
+  });
+}
+
+/** Codex: `codex queue` enqueues the next user turn on the local app-server daemon. */
+function deliverCodex(delivery, event) {
+  return new Promise((resolve, reject) => {
+    const binary = process.env.SIDEVOICE_CODEX_BIN || 'codex';
+    const args = ['queue', '--thread', delivery.thread, '--message', envelope(event)];
+    execFile(binary, args, { timeout: 30_000, maxBuffer: 1 << 20 }, (error, stdout, stderr) => {
+      if (error) return reject(new Error((stderr || stdout || error.message).toString().trim().slice(0, 400)));
+      resolve({ status: 'accepted', detail: 'codex queue confirmed the thread' });
+    });
+  });
+}
+
+/** Fallback: an HTTP receiver next to the harness (the slimmed Codex Desktop bridge speaks this). */
+async function deliverHttp(delivery, event) {
+  const response = await fetch(delivery.url, {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ thread_id: delivery.thread, text: event.text, message_id: event.message_id,
+      session_id: event.session_id, revision: event.revision, channel: event.channel || 'voice' }),
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!response.ok) throw new Error(`Harness delivery failed (${response.status})`);
+  return { status: 'accepted', detail: `receiver answered ${response.status}` };
+}
+
+export const adapters = { 'claude-uds': deliverClaude, 'codex-queue': deliverCodex, http: deliverHttp };
+
+export function deliver(delivery, event) {
+  const adapter = adapters[delivery?.kind];
+  if (!adapter) throw new Error(`Unknown delivery kind: ${delivery?.kind}`);
+  return adapter(delivery, event);
+}

package/cli.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/** `sidevoice <mcp|pair|connector> …` — one bin, three entry points. */
+const [, , command, ...rest] = process.argv;
+const entries = { mcp: './mcp.mjs', pair: './pair.mjs', connector: './connector.mjs' };
+if (!entries[command]) { console.error('usage: sidevoice <mcp|pair|connector> [args]'); process.exit(2); }
+process.argv.splice(2, 1);
+await import(entries[command]);

package/connector.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/** One connector per host: an outbound WebSocket to the room, every binding multiplexed over it,
+ *  and the last mile chosen per binding. Node 22+, no dependencies. Façades talk to it over a
+ *  local socket; a binding lives exactly as long as the façade connection that registered it. */
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { mkdirSync, openSync, closeSync, writeFileSync, readFileSync, unlinkSync, renameSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { deliver } from './adapters.mjs';
+
+export const PROTOCOL = 1;
+const dataDir = process.env.SIDEVOICE_DATA_DIR || path.join(os.homedir(), '.sidevoice');
+const socketPath = process.env.SIDEVOICE_CONNECTOR_SOCKET || path.join(dataDir, 'connector.sock');
+const lockPath = socketPath + '.lock';
+const outboxPath = path.join(dataDir, 'outbox.json');
+const credentialsPath = process.env.SIDEVOICE_CREDENTIALS || path.join(dataDir, 'credentials.json');
+const idleMs = Number(process.env.SIDEVOICE_CONNECTOR_IDLE_MS || 15_000);
+const hostId = process.env.SIDEVOICE_HOST_ID || os.hostname();
+
+function credentials() {
+  let saved = {};
+  try { saved = JSON.parse(readFileSync(credentialsPath, 'utf8')); } catch {}
+  const url = process.env.SIDEVOICE_URL || saved.url;
+  const connector_id = process.env.SIDEVOICE_CONNECTOR_ID || saved.connector_id;
+  const token = process.env.SIDEVOICE_CONNECTOR_TOKEN || saved.token;
+  if (!url || !connector_id || !token) throw new Error(`Not paired: run pair.mjs first (looked in ${credentialsPath})`);
+  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');
+  return { url, connector_id, token };
+}
+
+function alive(pid) { try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; } }
+function acquireLock() {
+  mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try { const fd = openSync(lockPath, 'wx', 0o600); writeFileSync(fd, String(process.pid)); closeSync(fd); return true; }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      let pid = 0; try { pid = Number(readFileSync(lockPath, 'utf8')); } catch {}
+      if (pid && alive(pid)) return false;          // A live connector holds it: we are redundant.
+      try { unlinkSync(lockPath); } catch {}         // Stale lock from a dead process.
+    }
+  }
+  return false;
+}
+
+const bindings = new Map();        // binding_id -> { binding_id, client_ref, harness, thread, title, delivery, owner, chain }
+const registering = new Map();     // client_ref -> { resolve, reject, timer }
+const publishing = new Map();      // event_id -> { resolve, timer }
+const clients = new Set();         // façade IPC connections
+let outbox = [];                   // speech frames not yet confirmed by the room
+let ws = null, connected = false, closed = false, reconnectTimer = null, idleTimer = null, reconnectAttempt = 0, lastError = null;
+let creds;
+
+function loadOutbox() { try { outbox = JSON.parse(readFileSync(outboxPath, 'utf8')); if (!Array.isArray(outbox)) outbox = []; } catch { outbox = []; } }
+function saveOutbox() {
+  const temporary = outboxPath + '.' + process.pid + '.tmp';
+  writeFileSync(temporary, JSON.stringify(outbox), { mode: 0o600 }); renameSync(temporary, outboxPath);
+}
+function send(frame) { if (ws?.readyState === WebSocket.OPEN) { ws.send(JSON.stringify(frame)); return true; } return false; }
+
+function open() {
+  if (closed || ws?.readyState === WebSocket.OPEN || ws?.readyState === WebSocket.CONNECTING) return;
+  const socket = ws = new WebSocket(creds.url);
+  socket.addEventListener('open', () => {
+    send({ type: 'connector.hello', protocol: PROTOCOL, connector_id: creds.connector_id, token: creds.token, host: hostId });
+  });
+  socket.addEventListener('message', event => { receive(JSON.parse(String(event.data))).catch(error => send({ type: 'connector.error', error: error.message })); });
+  const lost = () => { if (ws === socket) { ws = null; connected = false; } reconnect(); };
+  // A refused connection surfaces as 'error' with no 'close', and the dead socket stays
+  // CONNECTING forever: forget it, or open() would never make another one.
+  socket.addEventListener('close', lost);
+  socket.addEventListener('error', lost);
+}
+function reconnect() {
+  if (closed || reconnectTimer) return;
+  const delay = Math.min(10_000, 250 * 2 ** Math.min(reconnectAttempt++, 6));
+  reconnectTimer = setTimeout(() => { reconnectTimer = null; open(); }, delay);
+}
+
+async function receive(frame) {
+  switch (frame.type) {
+    case 'connector.welcome':
+      connected = true; reconnectAttempt = 0; lastError = null;
+      for (const binding of bindings.values()) {
+        // `local-*` is only a connector-side placeholder while the first
+        // registration waits for the room to mint its durable binding id.
+        // Sending it back makes the room correctly reject it as foreign.
+        const frame = { type: 'binding.register', client_ref: binding.client_ref,
+          harness: binding.harness, thread: binding.thread, title: binding.title,
+          inbound: binding.inbound, focus: false };
+        if (!binding.binding_id.startsWith('local-')) frame.binding_id = binding.binding_id;
+        send(frame);
+      }
+      for (const speech of outbox) send(speech);
+      return;
+    case 'heartbeat': send({ type: 'heartbeat.ack', nonce: frame.nonce }); return;
+    case 'binding.registered': {
+      const binding = [...bindings.values()].find(b => b.client_ref === frame.client_ref);
+      if (binding && binding.binding_id !== frame.binding_id) { bindings.delete(binding.binding_id); binding.binding_id = frame.binding_id; bindings.set(frame.binding_id, binding); }
+      registering.get(frame.client_ref)?.resolve(frame); return;
+    }
+    case 'binding.rejected': registering.get(frame.client_ref)?.reject(new Error(frame.error || 'Binding rejected')); return;
+    case 'speech.published': {
+      outbox = outbox.filter(speech => speech.event_id !== frame.event_id); saveOutbox();
+      publishing.get(frame.event_id)?.resolve(frame); return;
+    }
+    case 'input.deliver': {
+      const binding = bindings.get(frame.binding_id);
+      if (!binding) { send({ type: 'input.ack', event_id: frame.event_id, status: 'unknown_binding' }); return; }
+      // One delivery at a time per binding keeps the user's turns in order.
+      binding.chain = (binding.chain || Promise.resolve()).then(async () => {
+        try {
+          const outcome = await deliver(binding.delivery, frame);
+          console.error(`[sidevoice] delivered ${frame.event_id} to ${binding.thread} via ${binding.delivery.kind}: ${outcome.status} (${outcome.detail})`);
+          send({ type: 'input.ack', event_id: frame.event_id, status: outcome.status, detail: outcome.detail });
+        } catch (error) {
+          console.error(`[sidevoice] delivery of ${frame.event_id} failed: ${error.message}`);
+          send({ type: 'input.ack', event_id: frame.event_id, status: 'failed', error: String(error.message || error).slice(0, 400) });
+        }
+      });
+      return;
+    }
+    case 'connector.error': lastError = frame.error; console.error('[sidevoice] room: ' + frame.error); return;
+  }
+}
+
+function snapshot() {
+  return { host: hostId, connected, protocol: PROTOCOL, outbox: outbox.length, room_error: lastError,
+    bindings: [...bindings.values()].map(({ binding_id, client_ref, harness, thread, title, delivery }) => ({ binding_id, client_ref, harness, thread, title, delivery: delivery.kind })) };
+}
+function scheduleExit() {
+  if (idleTimer) clearTimeout(idleTimer);
+  idleTimer = setTimeout(() => { if (clients.size === 0 && bindings.size === 0) shutdown(); }, idleMs);
+}
+function shutdown() {
+  closed = true; clearTimeout(reconnectTimer); clearTimeout(idleTimer);
+  try { ws?.close(); } catch {}
+  server.close();
+  try { if (Number(readFileSync(lockPath, 'utf8')) === process.pid) { unlinkSync(socketPath); unlinkSync(lockPath); } } catch {}
+  process.exit(0);
+}
+
+async function command(client, input) {
+  const params = input.params || {};
+  switch (input.method) {
+    case 'register': {
+      const { client_ref, harness, thread, title, delivery, inbound } = params;
+      if (!client_ref || !thread || !delivery?.kind) throw new Error('client_ref, thread and delivery are required');
+      const existing = [...bindings.values()].find(b => b.client_ref === client_ref);
+      if (existing) { existing.owner = client; existing.delivery = delivery; client.bindings.add(existing); return { binding_id: existing.binding_id, thread, connected }; }
+      const local_id = 'local-' + randomUUID();
+      const binding = { binding_id: local_id, client_ref, harness, thread, title, delivery, inbound, owner: client };
+      bindings.set(local_id, binding); client.bindings.add(binding); clearTimeout(idleTimer); open();
+      const frame = await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { registering.delete(client_ref); reject(new Error(connected ? 'The room did not confirm the binding' : 'The room is unreachable; retrying in the background')); }, 10_000);
+        registering.set(client_ref, { resolve: f => { clearTimeout(timer); registering.delete(client_ref); resolve(f); }, reject: e => { clearTimeout(timer); registering.delete(client_ref); reject(e); } });
+        if (!send({ type: 'binding.register', client_ref, harness, thread, title, inbound })) { /* sent on welcome */ }
+      }).catch(error => { if (!connected) return null; bindings.delete(binding.binding_id); client.bindings.delete(binding); throw error; });
+      return { binding_id: frame?.binding_id || binding.binding_id, thread, connected, pending: !frame };
+    }
+    case 'publish': {
+      const binding = bindings.get(params.binding_id) || [...bindings.values()].find(b => b.client_ref === params.client_ref);
+      if (!binding) throw new Error('Unknown binding');
+      const speech = { type: 'speech.publish', event_id: params.event_id || randomUUID(), binding_id: binding.binding_id,
+        session_id: params.session_id, revision: params.revision, utterance_id: params.utterance_id || randomUUID(), text: params.text, language: params.language };
+      outbox.push(speech); saveOutbox();
+      if (!send(speech)) return { status: 'queued', utterance_id: speech.utterance_id };
+      const reply = await new Promise(resolve => {
+        const timer = setTimeout(() => { publishing.delete(speech.event_id); resolve(null); }, 15_000);
+        publishing.set(speech.event_id, { resolve: f => { clearTimeout(timer); publishing.delete(speech.event_id); resolve(f); } });
+      });
+      if (!reply) return { status: 'queued', utterance_id: speech.utterance_id };
+      const { type, event_id, ...result } = reply;
+      return result;
+    }
+    case 'unregister': {
+      const binding = bindings.get(params.binding_id);
+      if (binding) { bindings.delete(binding.binding_id); binding.owner?.bindings.delete(binding); if (!binding.binding_id.startsWith('local-')) send({ type: 'binding.unregister', binding_id: binding.binding_id }); }
+      scheduleExit(); return snapshot();
+    }
+    case 'status': return snapshot();
+    default: throw new Error('Unknown connector command');
+  }
+}
+
+function serve(socket) {
+  const client = { socket, bindings: new Set() };
+  clients.add(client); clearTimeout(idleTimer);
+  let buffer = '';
+  socket.on('data', chunk => {
+    buffer += chunk;
+    if (buffer.length > 1 << 20) { socket.destroy(); return; }
+    let index;
+    while ((index = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);
+      if (!line.trim()) continue;
+      let input; try { input = JSON.parse(line); } catch { socket.write(JSON.stringify({ ok: false, error: 'Invalid JSON' }) + '\n'); continue; }
+      command(client, input).then(result => socket.write(JSON.stringify({ id: input.id, ok: true, result }) + '\n'))
+        .catch(error => socket.write(JSON.stringify({ id: input.id, ok: false, error: error.message }) + '\n'));
+    }
+  });
+  socket.on('error', () => {});
+  socket.on('close', () => {
+    clients.delete(client);
+    // The façade is gone: so is every conversation it spoke for.
+    for (const binding of client.bindings) { bindings.delete(binding.binding_id); if (!binding.binding_id.startsWith('local-')) send({ type: 'binding.unregister', binding_id: binding.binding_id }); }
+    scheduleExit();
+  });
+}
+
+creds = credentials();
+if (!acquireLock()) process.exit(0);
+loadOutbox();
+try { unlinkSync(socketPath); } catch {}
+const server = net.createServer(serve);
+await new Promise((resolve, reject) => server.once('error', reject).listen(socketPath, resolve));
+process.on('SIGTERM', shutdown); process.on('SIGINT', shutdown);
+scheduleExit();
+open();

package/harness-claude.mjs

@@ -0,0 +1,88 @@
+/** What Claude Code will do with a message we post to a session's inbox, decided before we post it.
+ *
+ *  A session that bypasses permission prompts holds an injected message for its user's approval
+ *  instead of delivering it, and the inbox sends us no receipt to say so — the write looks
+ *  identical either way. So the only honest moment to find out is at voice_connect, from the
+ *  session's own launch flags and settings. Best effort by design: a managed policy layer we
+ *  cannot read could tighten this further, and the result says so rather than pretending.
+ *  Documented at https://code.claude.com/docs/en/cross-session-messaging */
+import { execFileSync } from 'node:child_process';
+import { readFileSync, readdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const configDir = () => process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+
+function readJson(file) {
+  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+/** The pid of the session with this id, from Claude Code's own session registry. */
+function sessionPid(sessionId) {
+  const registry = path.join(configDir(), 'sessions');
+  let entries = [];
+  try { entries = readdirSync(registry).filter(name => name.endsWith('.json')); } catch { return null; }
+  for (const name of entries) {
+    const record = readJson(path.join(registry, name));
+    if (record?.sessionId === sessionId) return record.pid ?? null;
+  }
+  return null;
+}
+
+/** The launch arguments of a pid, via ps so this works the same on Linux and macOS. */
+function launchArgs(pid) {
+  if (!pid) return '';
+  try { return execFileSync('ps', ['-o', 'args=', '-p', String(pid)], { encoding: 'utf8', timeout: 4000 }).trim(); }
+  catch { return ''; }
+}
+
+function flag(args, name) {
+  const match = args.match(new RegExp(`${name}[= ]('[^']*'|"[^"]*"|\\S+)`));
+  if (!match) return undefined;
+  return match[1].replace(/^['"]|['"]$/g, '');
+}
+
+/** `--settings` takes inline JSON or a path to a file; both may carry crossSessionInbound. */
+function settingsFromFlag(args) {
+  const value = flag(args, '--settings');
+  if (!value) return null;
+  if (value.trim().startsWith('{')) { try { return JSON.parse(value); } catch { return null; } }
+  return readJson(value);
+}
+
+const BYPASS_MODES = new Set(['bypassPermissions']);
+
+/** Will an injected message be delivered to this Claude session, or held for its user? */
+export function inspectInbound(sessionId) {
+  const pid = sessionPid(sessionId);
+  const args = launchArgs(pid);
+  const user = readJson(path.join(configDir(), 'settings.json')) || {};
+  const flagged = settingsFromFlag(args) || {};
+  const mode = flag(args, '--permission-mode') || user.permissions?.defaultMode || 'default';
+  // Launch flags beat user settings; a managed policy layer could still tighten either.
+  const inbound = flagged.crossSessionInbound ?? user.crossSessionInbound;
+  const bypassing = BYPASS_MODES.has(mode);
+  if (!bypassing) return { ok: true, mode, crossSessionInbound: inbound ?? null };
+  if (inbound === 'accept') return { ok: true, mode, crossSessionInbound: inbound };
+  return {
+    ok: false,
+    mode,
+    crossSessionInbound: inbound ?? null,
+    reason: inbound === 'refuse'
+      ? 'This session refuses messages from other local processes (crossSessionInbound is "refuse").'
+      : 'This session bypasses permission prompts, so Claude Code holds messages from other local '
+        + 'processes for the user to approve instead of delivering them, and it sends no receipt to '
+        + 'say so. Voice will appear to be sent and nothing will arrive.',
+    remedy: inbound === 'refuse'
+      ? 'Change crossSessionInbound from "refuse" to "accept", or start the session in a permission '
+        + 'mode that prompts.'
+      : 'Two ways out. Per session: start it with --settings \'{"crossSessionInbound":"accept"}\'. '
+        + 'For every session on this machine: add "crossSessionInbound": "accept" to '
+        + `${path.join(configDir(), 'settings.json')} — that takes effect immediately, releases any `
+        + 'messages already held, and also lets any other local process post into all your sessions, '
+        + 'which is the safeguard it removes. Or run the conversation in a prompting mode such as '
+        + '--permission-mode auto.',
+    // Said plainly so nothing downstream reports this as certain.
+    confidence: pid ? 'read from the session launch flags and settings' : 'settings only; the session process was not found',
+  };
+}

package/mcp.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/** Stdio MCP façade for one conversation. It holds no connection to the room: it starts or reuses
+ *  the host's connector and keeps one local connection to it for as long as this session lives. */
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { inspectInbound } from './harness-claude.mjs';
+
+const dataDir = process.env.SIDEVOICE_DATA_DIR || path.join(os.homedir(), '.sidevoice');
+const socketPath = process.env.SIDEVOICE_CONNECTOR_SOCKET || path.join(dataDir, 'connector.sock');
+const connectorPath = fileURLToPath(new URL('./connector.mjs', import.meta.url));
+
+const INSTRUCTIONS = `Sidevoice connects this conversation to the user's voice room.
+- Call voice_connect only when the user asks to join the voice room or enable voice for this conversation; never as a side effect.
+- Voice input arrives as a user message that starts with a JSON header ({"channel":"voice","session_id":...,"revision":...,"message_id":...}) followed by the user's literal words. Treat the header as opaque reply metadata; if the same message_id arrives twice, it is a redelivery: do not act on it again.
+- For substantive work, one incoming voice message may receive multiple voice_say publications: an immediate acknowledgement that states what was understood and the next action, meaningful progress checkpoints while work continues, and a final result. Use the same original session_id and revision for every publication, with distinct utterances; do not manufacture filler or narrate every tool call.
+- A progress publication is not itself a listening point. Divide substantive execution into bounded steps and, after each tool result or operational boundary, process newly arrived user input before starting the next step. Do not add artificial sleeps or fixed pauses.
+- If a new user message arrives during active work, treat it as an addition, refinement, or replacement according to its meaning. Stop not-yet-started obsolete work, preserve completed work that remains useful, acknowledge the new interpretation before continuing, and do not later answer a stale request. A tool already running may finish before the correction takes effect; delegation is not a substitute for listening.
+- A "published" voice_say result means the room stored it, not that the user heard it. If publication fails, continue in writing.
+- A message with "channel":"room-control" is an instruction from the room (for example: continue in writing); it is not a voice turn to answer aloud.
+- voice_status reports whether the room can currently reach this conversation.
+- If voice_connect returns inbound.ok false, voice will look sent and never arrive: this harness holds or refuses messages posted by other local processes. Tell the user what inbound.reason says, offer inbound.remedy in your own words including what safeguard the machine-wide option removes, and let them choose. Do not change their settings without being asked to.`;
+
+/** Who this façade speaks for, decided by what spawned it — never by the model. */
+function identity(meta) {
+  if (process.env.CLAUDE_CODE_SESSION_ID && process.env.CLAUDE_CODE_MESSAGING_SOCKET) {
+    return { harness: 'claude', thread: process.env.CLAUDE_CODE_SESSION_ID,
+      delivery: { kind: 'claude-uds', socket: process.env.CLAUDE_CODE_MESSAGING_SOCKET, token: process.env.CLAUDE_CODE_MESSAGING_TOKEN || '' } };
+  }
+  let turn = meta?.['x-codex-turn-metadata'] || {};
+  if (typeof turn === 'string') { try { turn = JSON.parse(turn); } catch { turn = {}; } }
+  const codexThread = meta?.['openai/threadId'] || meta?.['openai/thread_id'] || meta?.codexThreadId || meta?.codex_thread_id || turn.thread_id || process.env.CODEX_THREAD_ID;
+  if (codexThread) {
+    const delivery = process.env.SIDEVOICE_DELIVERY_URL ? { kind: 'http', url: process.env.SIDEVOICE_DELIVERY_URL, thread: codexThread } : { kind: 'codex-queue', thread: codexThread };
+    return { harness: 'codex', thread: codexThread, delivery };
+  }
+  if (process.env.SIDEVOICE_THREAD && process.env.SIDEVOICE_DELIVERY_URL) {
+    return { harness: process.env.SIDEVOICE_HARNESS || 'http', thread: process.env.SIDEVOICE_THREAD, delivery: { kind: 'http', url: process.env.SIDEVOICE_DELIVERY_URL, thread: process.env.SIDEVOICE_THREAD } };
+  }
+  throw new Error('Cannot tell which conversation this is: not launched by Claude Code or Codex, and no SIDEVOICE_THREAD/SIDEVOICE_DELIVERY_URL set');
+}
+
+// ----- one persistent connection to the connector -----
+let ipc = null, ipcBuffer = '', ipcSerial = 0;
+const ipcWaiting = new Map();
+function connectIpc() {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    socket.once('error', reject);
+    socket.on('connect', () => {
+      socket.removeListener('error', reject);
+      socket.on('error', () => {});
+      socket.on('close', () => { if (ipc === socket) ipc = null; for (const w of ipcWaiting.values()) w.reject(new Error('Connector went away')); ipcWaiting.clear(); });
+      socket.on('data', chunk => {
+        ipcBuffer += chunk; let index;
+        while ((index = ipcBuffer.indexOf('\n')) >= 0) {
+          const line = ipcBuffer.slice(0, index); ipcBuffer = ipcBuffer.slice(index + 1);
+          let reply; try { reply = JSON.parse(line); } catch { continue; }
+          const waiting = ipcWaiting.get(reply.id); if (!waiting) continue; ipcWaiting.delete(reply.id);
+          reply.ok ? waiting.resolve(reply.result) : waiting.reject(new Error(reply.error));
+        }
+      });
+      ipc = socket; resolve(socket);
+    });
+  });
+}
+async function ensureConnector() {
+  if (ipc) return ipc;
+  try { return await connectIpc(); } catch {}
+  const child = spawn(process.execPath, [connectorPath], { detached: true, stdio: 'ignore', env: process.env });
+  child.unref();
+  for (let attempt = 0; attempt < 40; attempt++) {
+    await new Promise(r => setTimeout(r, 100));
+    try { return await connectIpc(); } catch {}
+  }
+  throw new Error('The Sidevoice connector did not start (is this host paired? see docs/INSTALL.md)');
+}
+async function rpc(method, params) {
+  await ensureConnector();
+  const id = ++ipcSerial;
+  return new Promise((resolve, reject) => { ipcWaiting.set(id, { resolve, reject }); ipc.write(JSON.stringify({ id, method, params }) + '\n'); });
+}
+
+// ----- tools -----
+const tools = [
+  { name: 'voice_connect', description: 'Connect this conversation to the voice room. Only on an explicit request to join or enable voice.',
+    inputSchema: { type: 'object', properties: { title: { type: 'string', description: 'Short label for this conversation in the room' } }, additionalProperties: false } },
+  { name: 'voice_say', description: 'Publish a concise spoken version of your reply to the room, with the session_id and revision from the voice message header.',
+    inputSchema: { type: 'object', properties: { text: { type: 'string' }, session_id: { type: 'string' }, revision: { type: 'integer', minimum: 0 }, utterance_id: { type: 'string' }, language: { type: 'string', enum: ['es', 'en', 'fr', 'it', 'pt', 'hi'] } }, required: ['text', 'session_id', 'revision'], additionalProperties: false } },
+  { name: 'voice_disconnect', description: 'Leave the voice room. The conversation and its work continue in writing.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+  { name: 'voice_status', description: 'Whether the room can currently reach this conversation.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+];
+let binding = null;
+async function invoke(name, args, meta) {
+  if (name === 'voice_status') {
+    const status = ipc ? await rpc('status', {}) : { connected: false, bindings: [] };
+    const inbound = binding?.harness === 'claude' ? inspectInbound(binding.client_ref) : { ok: true };
+    return { joined: !!binding, room_reachable: status.connected, room_error: status.room_error || null,
+             binding_id: binding?.binding_id || null, harness: binding?.harness || null, inbound };
+  }
+  if (name === 'voice_connect') {
+    const who = identity(meta);
+    const title = (args.title || process.env.SIDEVOICE_TITLE || path.basename(process.cwd())).slice(0, 200);
+    // Refuse rather than join a room we cannot hear from: a conversation whose harness holds
+    // what the room posts would sit in the list looking present while the user talks to nobody.
+    const inbound = who.harness === 'claude' ? inspectInbound(who.thread) : { ok: true };
+    if (inbound.ok === false) {
+      const error = new Error(`No se conecta esta conversación: ${inbound.reason} ${inbound.remedy}`);
+      error.data = { inbound };
+      throw error;
+    }
+    const result = await rpc('register', { client_ref: who.thread, harness: who.harness, thread: who.thread, title, delivery: who.delivery, inbound });
+    binding = { ...result, harness: who.harness, client_ref: who.thread };
+    return { status: result.pending ? 'joining' : 'joined', harness: who.harness, conversation: who.thread,
+             binding_id: result.binding_id, delivery: 'push', room_reachable: result.connected, inbound };
+  }
+  if (!binding) throw new Error('Not connected to the voice room: call voice_connect first (only if the user asked).');
+  if (name === 'voice_say') {
+    const result = await rpc('publish', { binding_id: binding.binding_id, client_ref: binding.client_ref, text: args.text, session_id: args.session_id, revision: args.revision, utterance_id: args.utterance_id, language: args.language });
+    return result.text_saved ? { status: 'published', text_saved: true, audio: result.status, reason: result.reason } : result;
+  }
+  if (name === 'voice_disconnect') { const result = await rpc('unregister', { binding_id: binding.binding_id }); binding = null; return { status: 'left', room_reachable: result.connected }; }
+  throw new Error('Unknown tool');
+}
+
+// ----- JSON-RPC over stdio -----
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', async chunk => {
+  input += chunk;
+  while (input.includes('\n')) {
+    const index = input.indexOf('\n'); const line = input.slice(0, index); input = input.slice(index + 1);
+    if (!line.trim()) continue;
+    let request; try { request = JSON.parse(line); } catch { continue; }
+    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 };
+      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 = {};
+      else throw Object.assign(new Error('Method not found'), { code: -32601 });
+    } catch (e) { error = { code: e.code || -32603, message: e.message }; }
+    process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: request.id, ...(error ? { error } : { result }) }) + '\n');
+  }
+});
+process.stdin.on('end', () => { ipc?.end(); process.exit(0); });

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@sidevoice/uplink",
+  "version": "0.2.0",
+  "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",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "sidevoice": "./cli.mjs"
+  },
+  "files": [
+    "cli.mjs",
+    "mcp.mjs",
+    "connector.mjs",
+    "adapters.mjs",
+    "harness-claude.mjs",
+    "pair.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/test_connector.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rubasace/sidevoice.git",
+    "directory": "packages/connector"
+  }
+}

package/pair.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/** One-time pairing: redeem the code shown by the room for this host's connector credential. */
+import os from 'node:os';
+import path from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
+
+const [room, code] = process.argv.slice(2);
+if (!room || !code) { console.error('usage: pair.mjs <room-url> <pairing-code>'); process.exit(2); }
+const base = new URL(room);
+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),
+});
+const body = await response.json().catch(() => ({}));
+if (!response.ok) { console.error('Pairing failed: ' + (body.detail || response.status)); process.exit(1); }
+const ws = new URL('/api/connectors/ws', base); ws.protocol = base.protocol === 'https:' ? 'wss:' : 'ws:';
+const dataDir = process.env.SIDEVOICE_DATA_DIR || path.join(os.homedir(), '.sidevoice');
+mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+const file = path.join(dataDir, 'credentials.json');
+writeFileSync(file, JSON.stringify({ url: ws.toString(), connector_id: body.connector_id, token: body.token, protocol: body.protocol }, null, 2), { mode: 0o600 });
+console.log(`Paired with ${base.origin} as connector ${body.connector_id}; credential saved to ${file}`);