@sidevoice/uplink 0.2.0 → 0.4.0

package/harness-contract.mjs

@@ -0,0 +1,116 @@
+/** The harness boundary. A known harness declares every capability; callers never infer support
+ *  from a missing method. Missing or malformed declarations remain unknown, never false. */
+
+export const CAPABILITIES = Object.freeze([
+  'deliver',
+  'inspectInbound',
+  'working',
+  'endOfTurn',
+  'sessionIdentity',
+]);
+
+export const SUPPORTED = 'supported';
+export const UNSUPPORTED = 'unsupported';
+export const UNKNOWN = 'unknown';
+const DECLARED_STATES = new Set([SUPPORTED, UNSUPPORTED]);
+
+export function capabilityState(harness, capability) {
+  const state = harness?.capabilities?.[capability];
+  return DECLARED_STATES.has(state) ? state : UNKNOWN;
+}
+
+export function advertisedCapabilities(harness) {
+  return Object.fromEntries(CAPABILITIES.map(capability => [capability, capabilityState(harness, capability)]));
+}
+
+/** `working` and `endOfTurn` are both answered by observation: a harness that supports either
+ *  implements `observe(thread, handlers)`, which watches what the harness itself writes about that
+ *  conversation and calls back — `working(bool, { turn_id })` on every transition it can see, and
+ *  `userMessage({ text, turn_id })` for every user message the conversation admits. It returns a
+ *  function that stops watching. Nothing is installed in the harness for this to work. */
+export function defineHarness(definition) {
+  if (!definition?.name) throw new Error('A harness needs a name');
+  for (const capability of CAPABILITIES) {
+    const state = definition.capabilities?.[capability];
+    if (!DECLARED_STATES.has(state)) throw new Error(`${definition.name} must declare ${capability}`);
+    const implemented = capability === 'working' || capability === 'endOfTurn' ? definition.observe : definition[capability];
+    if (state === SUPPORTED && typeof implemented !== 'function') {
+      throw new Error(`${definition.name} declares ${capability} supported but does not implement it`);
+    }
+  }
+  return Object.freeze({ ...definition, capabilities: Object.freeze({ ...definition.capabilities }) });
+}
+
+/** The header before the user's literal words, and — for a voice message — the note after them that
+ *  asks the conversation to speak first. The note travels inside the message because it is the only
+ *  thing every harness delivers without anything installed; the instructions name it as not the user's. */
+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,
+  };
+  const note = header.channel === 'voice' ? '\n\n' + nudge(header) : '';
+  return JSON.stringify(header) + '\n\n' + event.text + note;
+}
+
+/** What the conversation is asked at the moment it reads a voice message. */
+export function nudge(header) {
+  return `[Sidevoice] A voice message from the room (session_id "${header.session_id}", revision ${header.revision}). `
+    + 'Before any other tool, publish a short spoken acknowledgement with voice_say that says what you understood and what you will do next, '
+    + 'using that session_id and revision; then continue the work and publish the result by voice as well.';
+}
+
+/** The header at the front of a delivered message, or null when the text is not one of ours. Works on
+ *  the text as a harness stores it, which may put its own line before the header. */
+export function voiceEnvelope(text) {
+  if (typeof text !== 'string') return null;
+  const start = text.indexOf('{"channel":');
+  if (start < 0) return null;
+  const end = text.indexOf('}', start);
+  if (end < 0) return null;
+  let header;
+  try { header = JSON.parse(text.slice(start, end + 1)); } catch { return null; }
+  if (!header || (header.channel !== 'voice' && header.channel !== 'room-control') || !header.message_id || !header.session_id || !Number.isInteger(header.revision)) return null;
+  return { channel: header.channel, message_id: header.message_id, session_id: header.session_id, revision: header.revision };
+}
+
+/** Follows a JSON-lines file the harness appends to: each complete new line is handed to `onLine` as
+ *  parsed JSON. From where the file is now, unless `catchUp` is set — then what is already there is
+ *  read first, with `replayed = true`, so a watcher can learn the current state without mistaking old
+ *  lines for news. The file may not exist yet — `locate` is asked again until it does. */
+export function tailJsonl(locate, onLine, { intervalMs = 400, catchUp = false, caughtUp = () => {} } = {}) {
+  let file = null, offset = null, remainder = '', replaying = false;
+  const poll = async () => {
+    const { statSync, openSync, readSync, closeSync } = await import('node:fs');
+    if (!file) { file = locate(); if (!file) return; }
+    let size;
+    try { size = statSync(file).size; } catch { file = null; offset = null; return; }
+    if (offset === null) {
+      if (!catchUp) { offset = size; return; }                // start at the end: only what happens from now on
+      offset = 0; replaying = true;
+    }
+    if (size < offset) { offset = 0; remainder = ''; }        // rewritten: read it again from the top
+    if (size === offset) return;
+    const fd = openSync(file, 'r');
+    try {
+      const buffer = Buffer.alloc(size - offset);
+      readSync(fd, buffer, 0, buffer.length, offset);
+      offset = size;
+      remainder += buffer.toString('utf8');
+    } finally { closeSync(fd); }
+    let index;
+    while ((index = remainder.indexOf('\n')) >= 0) {
+      const line = remainder.slice(0, index); remainder = remainder.slice(index + 1);
+      if (!line.trim()) continue;
+      let parsed; try { parsed = JSON.parse(line); } catch { continue; }
+      try { onLine(parsed, replaying); } catch {}
+    }
+    if (replaying) { replaying = false; try { caughtUp(); } catch {} }
+  };
+  const timer = setInterval(() => { poll().catch(() => {}); }, intervalMs);
+  timer.unref?.();
+  poll().catch(() => {});
+  return () => clearInterval(timer);
+}

package/harness-http.mjs

@@ -0,0 +1,39 @@
+/** Generic HTTP harness used by explicitly configured external receivers. */
+import { defineHarness, SUPPORTED, UNSUPPORTED } from './harness-contract.mjs';
+
+async function deliver(delivery, event) {
+  if (delivery?.kind !== 'http') throw new Error(`Unsupported HTTP delivery kind: ${delivery?.kind}`);
+  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}` };
+}
+
+function sessionIdentity({ env = process.env } = {}) {
+  if (!env.SIDEVOICE_THREAD || !env.SIDEVOICE_DELIVERY_URL) return null;
+  return {
+    harness: env.SIDEVOICE_HARNESS || 'http',
+    thread: env.SIDEVOICE_THREAD,
+    delivery: { kind: 'http', url: env.SIDEVOICE_DELIVERY_URL, thread: env.SIDEVOICE_THREAD },
+  };
+}
+
+export const httpHarness = defineHarness({
+  name: 'http',
+  capabilities: {
+    deliver: SUPPORTED,
+    inspectInbound: UNSUPPORTED,
+    working: UNSUPPORTED,
+    endOfTurn: UNSUPPORTED,
+    sessionIdentity: SUPPORTED,
+  },
+  deliver,
+  sessionIdentity,
+});
+
+export default httpHarness;

package/harnesses.mjs

@@ -0,0 +1,19 @@
+/** Registry and selection for the harness modules. The façade and connector ask this registry;
+ *  neither contains harness-name branches. */
+import { claudeHarness } from './harness-claude.mjs';
+import { codexHarness } from './harness-codex.mjs';
+import { httpHarness } from './harness-http.mjs';
+
+export const harnesses = Object.freeze({ claude: claudeHarness, codex: codexHarness, http: httpHarness });
+
+export function harnessFor(name) {
+  return harnesses[name] || httpHarness;
+}
+
+export function identifyHarness(meta, env = process.env) {
+  for (const harness of [claudeHarness, codexHarness, httpHarness]) {
+    const identity = harness.sessionIdentity({ meta, env });
+    if (identity?.delivery) return { ...identity, module: harness };
+  }
+  throw new Error('Cannot tell which conversation this is: not launched by Claude Code or Codex, and no SIDEVOICE_THREAD/SIDEVOICE_DELIVERY_URL set');
+}

package/install.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/** `sidevoice install` — put this version of Sidevoice in front of the harnesses on this machine.
+ *
+ *  It registers the MCP server (re-pinned to this version when an older one was registered), installs
+ *  the skill, says what it changed, and is safe to run twice: run it again after an upgrade and the
+ *  harness points at the new version. It pairs with nothing. Pairing is a person's act — the room shows
+ *  a one-time code to whoever is in it, and a conversation asks for it the first time it joins — so
+ *  the installer only reports whether this machine is paired, and with which room.
+ *
+ *  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 os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pairedRoom } from './pair.mjs';
+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. */
+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'] };
+}
+
+export function flag(argv, name) {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : undefined;
+}
+
+/** Which harnesses this machine has, by what they leave behind. */
+export function harnessesPresent(env = process.env) {
+  const found = [];
+  if (existsSync(env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'))) found.push('claude');
+  if (existsSync(env.CODEX_HOME || path.join(os.homedir(), '.codex'))) found.push('codex');
+  return found;
+}
+
+function claude(args, env) {
+  return execFileSync(env.SIDEVOICE_CLAUDE_BIN || 'claude', args, { encoding: 'utf8', timeout: 30_000, env, stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+/** What Claude Code currently runs for `sidevoice`, read from its own `mcp get`: null when nothing is
+ *  registered or there is no `claude` to ask. The scope matters — only a user-scope entry is ours to move. */
+export function claudeRegistration(env = process.env) {
+  let output;
+  try { output = claude(['mcp', 'get', 'sidevoice'], env); } catch { return null; }
+  const field = name => (output.match(new RegExp(`^\\s*${name}:\\s*(.*)$`, 'm')) || [])[1]?.trim() ?? '';
+  const command = field('Command'), args = field('Args');
+  if (!command) return null;
+  return { scope: /user/i.test(field('Scope')) ? 'user' : 'other', line: [command, args].filter(Boolean).join(' ') };
+}
+
+function registerWithClaude(done, env) {
+  const { command, args } = serverCommand(env);
+  const wanted = [command, ...args].join(' ');
+  const manual = `claude mcp add --scope user sidevoice -- ${wanted}`;
+  const current = claudeRegistration(env);
+  if (current?.line === wanted) { done.push('Claude Code already runs this version of the MCP server.'); return; }
+  if (current && current.scope !== 'user') {
+    done.push(`Claude Code has a sidevoice MCP server registered outside user scope (${current.line}); not touched. To move it:\n    ${manual}`);
+    return;
+  }
+  try {
+    if (current) claude(['mcp', 'remove', '--scope', 'user', 'sidevoice'], env);
+    claude(['mcp', 'add', '--scope', 'user', 'sidevoice', '--', command, ...args], env);
+    done.push(current ? `Re-pointed Claude Code's MCP server to this version (was: ${current.line}).`
+                      : 'Registered the MCP server with Claude Code (user scope).');
+  } catch (error) {
+    done.push(`Could not register with Claude Code automatically (${(error.message || '').split('\n')[0]}). Run:\n    ${manual}`);
+  }
+}
+
+/** Codex keeps one machine-wide file that may hold anything its user put there: we never rewrite it. */
+export function codexInstructions(env = process.env) {
+  const { command, args } = serverCommand(env);
+  return [
+    `Add to ${env.CODEX_HOME || path.join(os.homedir(), '.codex')}/config.toml — it is machine-wide and`,
+    'this package does not rewrite it:',
+    '',
+    '  [mcp_servers.sidevoice]',
+    `  command = "${command}"`,
+    `  args = [${args.map(a => `"${a}"`).join(', ')}]`,
+    '',
+    'Then restart Codex. That is all: read receipts and working state come from what Codex records about the thread.',
+  ].join('\n');
+}
+
+/** Claude Code holds messages from other local processes when a session bypasses permission prompts. */
+export function inboundWarning(env = process.env) {
+  const settings = path.join(env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'), 'settings.json');
+  let parsed = {};
+  try { parsed = JSON.parse(readFileSync(settings, 'utf8')); } catch { return null; }
+  if (parsed.crossSessionInbound) return null;
+  if (parsed.permissions?.defaultMode !== 'bypassPermissions') return null;
+  return [
+    'This machine runs Claude Code sessions in bypassPermissions, and those hold what the room sends',
+    'instead of delivering it — voice looks sent and never arrives. Either start a session with',
+    `  --settings '{"crossSessionInbound":"accept"}'`,
+    `or add "crossSessionInbound": "accept" to ${settings}. That second one lets any local process post`,
+    'into every Claude session on this machine, which is the safeguard it removes: your call, not ours.',
+  ].join('\n');
+}
+
+export async function install(argv = process.argv.slice(2), env = process.env) {
+  const stray = argv.find(item => !item.startsWith('-') && argv[argv.indexOf(item) - 1] !== '--harness');
+  if (stray) throw new Error(`usage: sidevoice install [--harness claude|codex]\n` +
+    `Pairing is not part of installing: a conversation asks for the room's code the first time it joins, ` +
+    `or run  sidevoice pair <room-url> <code>  with the code the room shows under "Emparejar conector".`);
+  const wanted = flag(argv, '--harness');
+  const harnesses = wanted ? [wanted] : harnessesPresent(env);
+  const done = [], next = [];
+
+  done.push(`Sidevoice ${VERSION}.`);
+  if (harnesses.includes('claude')) {
+    registerWithClaude(done, env);
+    const outcome = installSkill(skillsDir([], env));
+    done.push(`Skill ${outcome.action} at ${outcome.target}.`);
+  }
+
+  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.');
+
+  if (harnesses.includes('claude')) {
+    next.push('In a conversation, run /voice-room to join the room.' +
+              (paired ? '' : ' The first time, the conversation asks you for the room\'s address and the one-time code the room shows under "Emparejar conector".'));
+    next.push('Sessions already open need a restart before they can see the skill.');
+    const warning = inboundWarning(env);
+    if (warning) next.push(warning);
+  }
+  if (harnesses.includes('codex')) next.push(codexInstructions(env));
+  if (!harnesses.length) next.push('No harness found on this machine. Pass --harness claude or --harness codex.');
+  return { done, next };
+}
+
+if (process.env.SIDEVOICE_INSTALL_MAIN === '1') {
+  try {
+    const { done, next } = await install();
+    for (const line of done) console.log('· ' + line);
+    if (next.length) {
+      console.log('\nLeft for you:');
+      for (const line of next) console.log('\n' + line);
+    }
+  } catch (error) { console.error(error.message); process.exit(1); }
+}

package/mcp.mjs

@@ -7,7 +7,9 @@ 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';
+import { advertisedCapabilities, capabilityState, SUPPORTED } from './harness-contract.mjs';
+import { harnessFor, identifyHarness } from './harnesses.mjs';
+import { pair, pairedRoom } from './pair.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');
@@ -15,34 +17,17 @@ 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.
+- 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, and ends with a line marked [Sidevoice] that is not the user's words: it asks you to acknowledge by voice first. 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 the user closes this conversation's voice channel from the room, the connection is removed: voice_say then fails saying so. Continue in writing and do not try to speak again; call voice_connect only when the user asks for voice again.
+- voice_status reports whether the room can currently reach this conversation, and which room this machine is paired with.
+- Pairing is the user's act, never yours. If voice_connect answers that this machine is not paired with the room (or is paired with a different one), ask the user for the room's address and the one-time pairing code the room shows them under "Emparejar conector" (it expires in ten minutes), then call voice_pair with both and voice_connect again. Never try to obtain a code from the room yourself, and do not offer to: the room only shows it to the person in it.
+- On Claude Code, /voice-room is a shortcut for the same joining steps. Read receipts and working state need nothing from you: the room learns them from what the harness records about 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();
@@ -86,40 +71,92 @@ async function rpc(method, params) {
 
 // ----- 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_connect', description: 'Connect this conversation to the voice room. Only on an explicit request to join or enable voice. Fails, saying what to ask the user, when this machine is not paired with the room.',
+    inputSchema: { type: 'object', properties: { title: { type: 'string', description: 'Short label for this conversation in the room' }, room: { type: 'string', description: 'The room\'s address (https://…) when the user names one; omitted, the room this machine is paired with' } }, additionalProperties: false } },
+  { name: 'voice_pair', description: 'Pair this machine with a room using the one-time code the user read from the room\'s interface ("Emparejar conector"). Only with a code the user gave you; one room per machine, a new pairing replaces the previous one.',
+    inputSchema: { type: 'object', properties: { room: { type: 'string', description: 'The room\'s address (https://…)' }, code: { type: 'string', description: 'The one-time pairing code shown by the room' } }, required: ['room', 'code'], 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;
+function originOf(room) {
+  try { return new URL(room).origin; } catch { throw new Error(`"${room}" is not a room address; expected something like https://voice.example`); }
+}
+/** Ask the user, do not guess: the code exists only on the room's screen. */
+function pairingNeeded(room, paired) {
+  const target = room ? originOf(room) : null;
+  if (!paired) return `This machine is not paired with ${target ? 'the room at ' + target : 'any room'}. Ask the user for the room's address${target ? ' (confirm ' + target + ')' : ''} and the one-time pairing code the room shows under "Emparejar conector", then call voice_pair with both. Do not fetch a code yourself.`;
+  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;
+}
+function inboundFor(harness, thread) {
+  return capabilityState(harness, 'inspectInbound') === SUPPORTED ? harness.inspectInbound(thread) : 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 };
+    const status = ipc ? await rpc('status', {}) : { connected: false, bindings: [], closed_by_room: [] };
+    // The room may have closed this conversation's voice since we joined: the connector is the truth.
+    const closed = !!binding && (status.closed_by_room || []).includes(binding.client_ref);
+    if (closed) binding = null;
+    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,
+             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.' } : {}) };
+  }
+  if (name === 'voice_pair') {
+    if (!args.room || !args.code) throw new Error('voice_pair needs the room\'s address and the code the user read from it.');
+    const previous = pairedRoom();
+    // The room shows the code in upper case and compares it that way; a dictated one arrives however it was heard.
+    const result = await pair(originOf(args.room), String(args.code).trim().toUpperCase());
+    // The connector that is up, if any, was started for the previous credential: let go of it so it can
+    // exit, and the next voice_connect starts one for this room. Other conversations still bound to the
+    // previous room keep that connector alive until they leave; they are not moved.
+    if (binding) { try { await rpc('unregister', { binding_id: binding.binding_id }); } catch {} binding = null; }
+    if (ipc) { ipc.end(); ipc = null; }
+    return { status: 'paired', room: result.origin, connector_id: result.connector_id,
+             ...(previous && previous.origin !== result.origin ? { replaced: previous.origin, note: 'Conversations on this machine still joined to the previous room keep it until they leave.' } : {}),
+             next: 'Call voice_connect to join.' };
   }
   if (name === 'voice_connect') {
-    const who = identity(meta);
+    const needed = pairingNeeded(args.room, pairedRoom());
+    if (needed) { const error = new Error(needed); error.data = { pairing_needed: true, room: args.room ? originOf(args.room) : null }; throw error; }
+    const who = identifyHarness(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 inbound = inboundFor(who.module, who.thread);
+    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 };
+    const capabilities = advertisedCapabilities(who.module);
+    // Which model is answering, read from the session's own launch line rather than asked of the model.
+    let engine = null;
+    try { engine = who.module.engine?.(who.thread) || null; } catch { engine = null; }
+    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 };
     return { status: result.pending ? 'joining' : 'joined', harness: who.harness, conversation: who.thread,
-             binding_id: result.binding_id, delivery: 'push', room_reachable: result.connected, inbound };
+             binding_id: result.binding_id, delivery: 'push', room_reachable: result.connected, capabilities, 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 });
+    let result;
+    try {
+      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 });
+    } catch (error) {
+      if (error.message === 'CLOSED_BY_ROOM') {
+        binding = null;
+        throw new Error('The user closed this conversation\'s voice channel from the room. Continue in writing and do not publish speech; call voice_connect again only if the user asks for voice.');
+      }
+      throw error;
+    }
     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 }; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sidevoice/uplink",
-  "version": "0.2.0",
+  "version": "0.4.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",
@@ -12,11 +12,17 @@
   },
   "files": [
     "cli.mjs",
+    "install.mjs",
     "mcp.mjs",
     "connector.mjs",
-    "adapters.mjs",
+    "harness-contract.mjs",
+    "harnesses.mjs",
     "harness-claude.mjs",
+    "harness-codex.mjs",
+    "harness-http.mjs",
     "pair.mjs",
+    "skill.mjs",
+    "skill/",
     "README.md"
   ],
   "scripts": {

package/pair.mjs

@@ -1,21 +1,53 @@
 #!/usr/bin/env node
-/** One-time pairing: redeem the code shown by the room for this host's connector credential. */
+/** One-time pairing: redeem the code shown by the room for this host's connector credential.
+ *
+ *  The code is the room's to give and the person's to carry: the room shows it to whoever is in it
+ *  ("Emparejar conector"), and only that person can hand it to this machine. Nothing here asks the
+ *  room for one — a caller that could would turn "you can reach the address" into "you are in the room". */
 import os from 'node:os';
 import path from 'node:path';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, 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}`);
+export function dataDir(env = process.env) {
+  return env.SIDEVOICE_DATA_DIR || path.join(os.homedir(), '.sidevoice');
+}
+
+/** 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;
+}
+
+/** Which room this machine is paired with, or null. */
+export function pairedRoom(env = process.env) {
+  try {
+    const saved = JSON.parse(readFileSync(path.join(dataDir(env), 'credentials.json'), 'utf8'));
+    if (!saved.url || !saved.connector_id || !saved.token) return null;
+    return { origin: roomOrigin(saved.url), connector_id: saved.connector_id };
+  } catch { return null; }
+}
+
+/** 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);
+  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) throw new Error('Pairing failed: ' + (body.detail || response.status));
+  const ws = new URL('/api/connectors/ws', base); ws.protocol = base.protocol === 'https:' ? 'wss:' : 'ws:';
+  const directory = dataDir(env);
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const file = path.join(directory, 'credentials.json');
+  writeFileSync(file, JSON.stringify({ url: ws.toString(), connector_id: body.connector_id, token: body.token, protocol: body.protocol }, null, 2), { mode: 0o600 });
+  return { file, connector_id: body.connector_id, origin: base.origin };
+}
+
+if (process.env.SIDEVOICE_PAIR_MAIN === '1') {
+  const [room, code] = process.argv.slice(2);
+  if (!room || !code) { console.error('usage: sidevoice pair <room-url> <pairing-code>   (the code is shown in the room under "Emparejar conector")'); process.exit(2); }
+  try {
+    const result = await pair(room, code);
+    console.log(`Paired with ${result.origin} as connector ${result.connector_id}; credential saved to ${result.file}`);
+  } catch (error) { console.error(error.message); process.exit(1); }
+}

package/skill/voice-room/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: voice-room
+description: Join the user's Sidevoice voice room with this conversation. Use when the user asks to enable voice, join the room or talk by voice; never as a side effect of other work.
+argument-hint: "[title for this conversation in the room]"
+metadata:
+  sidevoice: installed copy; the source is skill/voice-room in @sidevoice/uplink, reinstall with `sidevoice skill install`
+---
+
+Join the voice room for this conversation and keep it reachable.
+
+1. Call `voice_status`. If it reports `joined` and `room_reachable`, say so in one line and stop.
+2. Call `voice_connect` with the title `$ARGUMENTS` when given, otherwise a short label of what this conversation is about. If the user named a room, pass its address as `room`.
+   If it fails saying this machine is not paired with the room (or is paired with a different one), ask the user for the room's address and the one-time code the room shows them under **Emparejar conector**; call `voice_pair` with both, then `voice_connect` again. Never try to get a code from the room yourself.
+3. Tell the user in one line whether the room can reach this conversation. If `inbound.ok` is false, relay `inbound.reason` and offer `inbound.remedy` in your own words, including what safeguard it removes; change nothing yourself.
+
+Nothing else is registered: the room learns that a message was read and whether this conversation is working from what Claude Code itself records about the session. How to behave once joined is in the Sidevoice MCP server's own instructions.