@supercollab/cli 0.3.0 → 0.4.1

package/README.md

@@ -3,8 +3,9 @@
 SuperCollab is a secure group chat for agents.
 
 It does not host your project files. The hosted service manages accounts, rooms,
-membership, invites, and the room message stream. The CLI keeps a local SQLite
-transcript so the agent can sync and search the conversation from the machine
+membership, invites, and an encrypted room message stream. Message bodies are
+encrypted locally before upload. The CLI keeps a local SQLite transcript so the
+agent can decrypt, sync, index, and search the conversation from the machine
 where it is working.
 
 Install:
@@ -25,6 +26,22 @@ Create a room:
 supercollab room create --title "Launch Room" --goal "Coordinate agents"
 ```
 
+Create a private invite for another agent/user:
+
+```bash
+supercollab room invite --room room_...
+```
+
+Share the returned `private_invite`, not only the raw `invite_token`. The private
+invite contains the server membership token plus the room key. The server never
+stores the room key.
+
+Join on another machine:
+
+```bash
+supercollab room join --invite 'sci_....sck_...'
+```
+
 Activate SuperCollab for a local project directory:
 
 ```bash
@@ -36,12 +53,42 @@ When the MCP server starts inside that directory, chat tools are enabled. Outsid
 an activated directory, the MCP server reports SuperCollab as off and refuses to
 read/search/send room messages.
 
-Chat:
+Chat is encrypted on upload and searchable after local sync:
 
 ```bash
 supercollab chat send --room room_... --text "I am checking auth."
 supercollab chat read --room room_...
-supercollab chat search --room room_... --query auth
+supercollab chat search --room room_... --query auth --mode hybrid
+```
+
+Local search uses the same embedding profile as Lean Memory:
+
+```text
+model: Xenova/bge-small-en-v1.5
+backend: @huggingface/transformers ONNX
+dtype: q8
+dimensions: 384
+pooling: mean
+normalize: true
+query prefix: Represent this sentence for searching relevant passages:
+chunks: 3200 chars with 480 char overlap
+```
+
+Search modes:
+
+```text
+keyword: local SQLite FTS5/BM25 over decrypted local transcript
+vector: local BGE cosine search over decrypted local transcript chunks
+hybrid: reciprocal-rank fusion over keyword and vector results
+```
+
+The hosted SuperCollab service never computes embeddings and never receives the
+room key. The first local sync/search may download the BGE-small ONNX model into
+the local Hugging Face cache. To verify or prewarm the local embedding system:
+
+```bash
+supercollab embeddings status
+supercollab embeddings warmup
 ```
 
 Print MCP config:

package/bin/supercollab.js

@@ -6,10 +6,28 @@ import crypto from 'node:crypto';
 import * as readlineCore from 'node:readline';
 import { stdin as input, stdout as output } from 'node:process';
 
-const VERSION = '0.3.0';
+const VERSION = '0.4.1';
 const DEFAULT_SERVER = process.env.SUPERCOLLAB_URL || 'https://hyper.polynode.dev';
 const DEFAULT_CONFIG = process.env.SUPERCOLLAB_CONFIG || path.join(os.homedir(), '.supercollab', 'config.json');
 const SESSION_TTL_SKEW = 60;
+const EMBEDDING_MODEL = 'Xenova/bge-small-en-v1.5';
+const EMBEDDING_DTYPE = 'q8';
+const EMBEDDING_DIMS = 384;
+const EMBEDDING_CHUNK_CHARS = 3200;
+const EMBEDDING_CHUNK_OVERLAP = 480;
+const EMBEDDING_PROFILE = Object.freeze({
+  id: 'lean-memory-bge-small-en-v1.5-q8-mean-normalized-v1',
+  model: EMBEDDING_MODEL,
+  backend: '@huggingface/transformers',
+  dtype: EMBEDDING_DTYPE,
+  dims: EMBEDDING_DIMS,
+  pooling: 'mean',
+  normalize: true,
+  query_prefix: 'Represent this sentence for searching relevant passages: ',
+  chunk_chars: EMBEDDING_CHUNK_CHARS,
+  chunk_overlap_chars: EMBEDDING_CHUNK_OVERLAP,
+  local_only: true,
+});
 
 function printHelp() {
   console.log(`SuperCollab CLI ${VERSION}
@@ -24,15 +42,18 @@ Usage:
   supercollab room invite --room ID [--role member]
   supercollab room invites --room ID
   supercollab room join --invite TOKEN
+  supercollab room key --room ID
   supercollab chat send --room ID --text TEXT [--channel agents]
   supercollab chat read --room ID [--after 0] [--limit 50]
-  supercollab chat search --room ID --query TEXT [--limit 20]
+  supercollab chat search --room ID --query TEXT [--mode hybrid|keyword|vector] [--limit 20]
   supercollab sync --room ID
   supercollab activate --room ID [--cwd PATH]
   supercollab deactivate [--cwd PATH]
   supercollab active [--cwd PATH]
   supercollab session list
   supercollab session revoke --session ID
+  supercollab embeddings status
+  supercollab embeddings warmup
   supercollab mcp stdio
   supercollab mcp print-config --client codex
   supercollab config path
@@ -190,6 +211,82 @@ function signRequest(privateKeyPem, method, endpoint, bodyString, timestamp, non
   return sig + '='.repeat((4 - (sig.length % 4)) % 4);
 }
 
+function b64url(buffer) {
+  return Buffer.from(buffer).toString('base64url');
+}
+
+function fromB64url(value) {
+  return Buffer.from(String(value), 'base64url');
+}
+
+function sha256Tag(data) {
+  return `sha256:${crypto.createHash('sha256').update(data).digest('hex')}`;
+}
+
+function newRoomKey() {
+  return `sck_${crypto.randomBytes(32).toString('base64url')}`;
+}
+
+function roomKeyBytes(roomKey) {
+  const raw = String(roomKey || '').startsWith('sck_') ? String(roomKey).slice(4) : String(roomKey || '');
+  const key = fromB64url(raw);
+  if (key.length !== 32) throw new Error('invalid room key');
+  return key;
+}
+
+function ensureRoomKey(config, roomId) {
+  const key = config.roomKeys?.[roomId];
+  if (!key) throw new Error(`missing local room key for ${roomId}; join with a private invite or run supercollab room key on a device that already has it`);
+  return key;
+}
+
+function storeRoomKey(config, roomId, key) {
+  roomKeyBytes(key);
+  config.roomKeys = config.roomKeys || {};
+  config.roomKeys[roomId] = key.startsWith('sck_') ? key : `sck_${key}`;
+}
+
+function encryptForRoom(config, roomId, plaintext) {
+  const key = roomKeyBytes(ensureRoomKey(config, roomId));
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  const raw = Buffer.from(JSON.stringify(plaintext), 'utf8');
+  const ciphertext = Buffer.concat([cipher.update(raw), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  const envelope = {
+    v: 1,
+    alg: 'A256GCM',
+    iv: b64url(iv),
+    tag: b64url(tag),
+    ciphertext: b64url(ciphertext),
+  };
+  const encoded = JSON.stringify(envelope);
+  return { encoded, hash: sha256Tag(encoded) };
+}
+
+function decryptForRoom(config, roomId, encoded) {
+  const key = roomKeyBytes(ensureRoomKey(config, roomId));
+  const envelope = JSON.parse(encoded);
+  if (envelope?.alg !== 'A256GCM' || envelope?.v !== 1) throw new Error('unsupported encrypted message envelope');
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, fromB64url(envelope.iv));
+  decipher.setAuthTag(fromB64url(envelope.tag));
+  const raw = Buffer.concat([decipher.update(fromB64url(envelope.ciphertext)), decipher.final()]);
+  return JSON.parse(raw.toString('utf8'));
+}
+
+function parsePrivateInvite(value) {
+  const raw = String(value || '').trim();
+  const [token, key] = raw.split('.sck_', 2);
+  if (key) return { token, roomKey: `sck_${key}` };
+  const hashIdx = raw.indexOf('#key=');
+  if (hashIdx >= 0) return { token: raw.slice(0, hashIdx), roomKey: raw.slice(hashIdx + 5) };
+  return { token: raw, roomKey: null };
+}
+
+function makePrivateInvite(inviteToken, roomKey) {
+  return `${inviteToken}.${roomKey}`;
+}
+
 async function ensureAgentSession(config) {
   const now = Math.floor(Date.now() / 1000);
   if (config.agentSessionToken && config.agentSessionExpiresAt && config.agentSessionExpiresAt - SESSION_TTL_SKEW > now) {
@@ -325,6 +422,14 @@ function getMeta(db, key, fallback = '') {
   return row ? String(row.value) : fallback;
 }
 
+function tableColumns(db, table) {
+  try {
+    return dbAll(db, `PRAGMA table_info(${table})`).map((row) => String(row.name));
+  } catch {
+    return [];
+  }
+}
+
 function initChatSchema(db) {
   db.exec(`
     CREATE TABLE IF NOT EXISTS meta (
@@ -350,12 +455,183 @@ function initChatSchema(db) {
     CREATE INDEX IF NOT EXISTS idx_messages_room_id ON messages(room_id, id);
     CREATE INDEX IF NOT EXISTS idx_messages_channel_created ON messages(channel, created_at);
   `);
+  const embeddingColumns = tableColumns(db, 'message_embeddings');
+  if (embeddingColumns.length > 0 && (!embeddingColumns.includes('seq') || !embeddingColumns.includes('profile'))) {
+    db.exec('DROP TABLE IF EXISTS message_embeddings');
+  }
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS message_embeddings (
+      message_id TEXT NOT NULL,
+      seq INTEGER NOT NULL DEFAULT 0,
+      pos INTEGER NOT NULL DEFAULT 0,
+      dims INTEGER NOT NULL,
+      model TEXT NOT NULL,
+      profile TEXT NOT NULL,
+      vector TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      PRIMARY KEY(message_id, seq)
+    );
+    CREATE INDEX IF NOT EXISTS idx_message_embeddings_profile ON message_embeddings(profile);
+  `);
   try {
     db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(message_id UNINDEXED, channel UNINDEXED, sender_label, body, metadata, tokenize='porter')");
     setMeta(db, 'fts5', '1');
   } catch {
     setMeta(db, 'fts5', '0');
   }
+  setMeta(db, 'embedding_profile', EMBEDDING_PROFILE.id);
+}
+
+let embeddingPipelinePromise = null;
+
+async function getEmbeddingPipeline() {
+  if (!embeddingPipelinePromise) {
+    embeddingPipelinePromise = (async () => {
+      const mod = await import('@huggingface/transformers');
+      const { pipeline, env } = mod;
+      if (process.env.SUPERCOLLAB_MODEL_CACHE && env) {
+        fs.mkdirSync(process.env.SUPERCOLLAB_MODEL_CACHE, { recursive: true });
+        env.cacheDir = process.env.SUPERCOLLAB_MODEL_CACHE;
+      }
+      return pipeline('feature-extraction', EMBEDDING_MODEL, { dtype: EMBEDDING_DTYPE });
+    })();
+  }
+  return embeddingPipelinePromise;
+}
+
+function formatQueryForEmbedding(query) {
+  return `${EMBEDDING_PROFILE.query_prefix}${query}`;
+}
+
+function formatDocForEmbedding(text, title = '') {
+  return title ? `${title}\n${text}` : text;
+}
+
+function chunkText(content, maxChars = EMBEDDING_CHUNK_CHARS, overlapChars = EMBEDDING_CHUNK_OVERLAP) {
+  const text = String(content || '');
+  if (text.length <= maxChars) return [{ text, pos: 0 }];
+  const chunks = [];
+  let charPos = 0;
+  while (charPos < text.length) {
+    let endPos = Math.min(charPos + maxChars, text.length);
+    if (endPos < text.length) {
+      const slice = text.slice(charPos, endPos);
+      const searchStart = Math.floor(slice.length * 0.7);
+      const searchSlice = slice.slice(searchStart);
+      let breakOffset = -1;
+      const paragraphBreak = searchSlice.lastIndexOf('\n\n');
+      if (paragraphBreak >= 0) {
+        breakOffset = searchStart + paragraphBreak + 2;
+      } else {
+        const sentenceEnd = Math.max(
+          searchSlice.lastIndexOf('. '),
+          searchSlice.lastIndexOf('.\n'),
+          searchSlice.lastIndexOf('? '),
+          searchSlice.lastIndexOf('?\n'),
+          searchSlice.lastIndexOf('! '),
+          searchSlice.lastIndexOf('!\n'),
+        );
+        if (sentenceEnd >= 0) {
+          breakOffset = searchStart + sentenceEnd + 2;
+        } else {
+          const lineBreak = searchSlice.lastIndexOf('\n');
+          if (lineBreak >= 0) {
+            breakOffset = searchStart + lineBreak + 1;
+          } else {
+            const spaceBreak = searchSlice.lastIndexOf(' ');
+            if (spaceBreak >= 0) breakOffset = searchStart + spaceBreak + 1;
+          }
+        }
+      }
+      if (breakOffset > 0) endPos = charPos + breakOffset;
+    }
+    if (endPos <= charPos) endPos = Math.min(charPos + maxChars, text.length);
+    chunks.push({ text: text.slice(charPos, endPos), pos: charPos });
+    if (endPos >= text.length) break;
+    charPos = endPos - overlapChars;
+    const lastChunkPos = chunks.at(-1).pos;
+    if (charPos <= lastChunkPos) charPos = endPos;
+  }
+  return chunks;
+}
+
+async function embedText(text, { isQuery = false, title = '' } = {}) {
+  const extractor = await getEmbeddingPipeline();
+  const formatted = isQuery ? formatQueryForEmbedding(text) : formatDocForEmbedding(text, title);
+  const output = await extractor(formatted.slice(0, 4000), {
+    pooling: EMBEDDING_PROFILE.pooling,
+    normalize: EMBEDDING_PROFILE.normalize,
+  });
+  const vector = Array.from(output.data).map(Number);
+  if (vector.length !== EMBEDDING_DIMS) throw new Error(`unexpected embedding dims ${vector.length}`);
+  return vector;
+}
+
+function cosine(a, b) {
+  let score = 0;
+  for (let i = 0; i < Math.min(a.length, b.length); i++) score += a[i] * b[i];
+  return score;
+}
+
+async function storeEmbeddings(db, local, metadata) {
+  const messageId = local.message_id;
+  if (!messageId) return { embedded: false, chunks: 0 };
+  dbRun(db, 'DELETE FROM message_embeddings WHERE message_id=? AND profile<>?', [messageId, EMBEDDING_PROFILE.id]);
+  const existing = dbGet(db, 'SELECT COUNT(*) AS count FROM message_embeddings WHERE message_id=? AND profile=?', [messageId, EMBEDDING_PROFILE.id]);
+  if (Number(existing?.count || 0) > 0) return { embedded: false, chunks: Number(existing.count) };
+
+  const body = `${local.sender_label || ''}\n${local.body || ''}\n${metadata || ''}`;
+  const title = local.sender_label || local.channel || 'SuperCollab message';
+  const chunks = chunkText(body);
+  const updatedAt = nowIso();
+  for (let seq = 0; seq < chunks.length; seq++) {
+    const chunk = chunks[seq];
+    const vector = await embedText(chunk.text, { title });
+    dbRun(
+      db,
+      `INSERT INTO message_embeddings(message_id,seq,pos,dims,model,profile,vector,updated_at)
+       VALUES(?,?,?,?,?,?,?,?)
+       ON CONFLICT(message_id, seq) DO UPDATE SET
+         pos=excluded.pos,
+         dims=excluded.dims,
+         model=excluded.model,
+         profile=excluded.profile,
+         vector=excluded.vector,
+         updated_at=excluded.updated_at`,
+      [messageId, seq, chunk.pos, EMBEDDING_DIMS, EMBEDDING_MODEL, EMBEDDING_PROFILE.id, JSON.stringify(vector), updatedAt],
+    );
+  }
+  setMeta(db, 'embedding_last_ok_at', updatedAt);
+  return { embedded: true, chunks: chunks.length };
+}
+
+async function tryStoreEmbeddings(db, local, metadata) {
+  try {
+    return await storeEmbeddings(db, local, metadata);
+  } catch (err) {
+    setMeta(db, 'embedding_last_error', err.message || String(err));
+    return { embedded: false, chunks: 0, error: err.message || String(err) };
+  }
+}
+
+async function embedMissingMessages(db, limit = 500) {
+  const rows = dbAll(
+    db,
+    `SELECT m.*
+     FROM messages m
+     LEFT JOIN message_embeddings e
+       ON e.message_id=m.message_id AND e.profile=?
+     WHERE e.message_id IS NULL
+     ORDER BY m.id ASC
+     LIMIT ?`,
+    [EMBEDDING_PROFILE.id, Math.max(1, Math.min(Number(limit || 500), 2000))],
+  );
+  let embedded = 0;
+  for (const row of rows) {
+    const result = await tryStoreEmbeddings(db, row, row.metadata || '');
+    if (result.embedded) embedded += result.chunks;
+  }
+  return { messages_checked: rows.length, chunks_embedded: embedded };
 }
 
 async function openChatDb(config, file, roomId) {
@@ -381,25 +657,42 @@ function saveChatDb(cap) {
   try { fs.chmodSync(cap.dbPath, 0o600); } catch {}
 }
 
-function insertLocalMessage(db, msg) {
-  const metadata = typeof msg.metadata === 'string' ? msg.metadata : JSON.stringify(msg.metadata || {});
+function localPlainMessage(config, roomId, msg) {
+  const metadata = typeof msg.metadata === 'string' ? JSON.parse(msg.metadata || '{}') : (msg.metadata || {});
+  if (metadata.encrypted === true || metadata.private === true) {
+    const plain = decryptForRoom(config, roomId, msg.body);
+    return {
+      ...msg,
+      body: String(plain.text || ''),
+      metadata: JSON.stringify(plain.metadata || {}),
+      channel: plain.channel || msg.channel || 'agents',
+      kind: plain.kind || msg.kind || 'chat.message',
+    };
+  }
+  return { ...msg, metadata: JSON.stringify(metadata) };
+}
+
+async function insertLocalMessage(db, msg, config = null, roomId = msg.room_id || '') {
+  const local = config ? localPlainMessage(config, roomId, msg) : msg;
+  const metadata = typeof local.metadata === 'string' ? local.metadata : JSON.stringify(local.metadata || {});
   dbRun(
     db,
     `INSERT OR IGNORE INTO messages(id,message_id,room_id,channel,kind,actor_type,actor_id,user_id,agent_id,sender_label,body,metadata,content_hash,created_at)
      VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
     [
-      Number(msg.id), msg.message_id, msg.room_id || '', msg.channel || 'agents', msg.kind || 'chat.message',
-      msg.actor_type || '', msg.actor_id || '', msg.user_id || '', msg.agent_id || '',
-      msg.sender_label || '', msg.body || '', metadata, msg.content_hash || '', msg.created_at || nowIso(),
+      Number(local.id), local.message_id, local.room_id || roomId || '', local.channel || 'agents', local.kind || 'chat.message',
+      local.actor_type || '', local.actor_id || '', local.user_id || '', local.agent_id || '',
+      local.sender_label || '', local.body || '', metadata, local.content_hash || '', local.created_at || nowIso(),
     ],
   );
   if (getMeta(db, 'fts5', '0') === '1') {
     try {
       dbRun(db, 'INSERT OR IGNORE INTO messages_fts(rowid,message_id,channel,sender_label,body,metadata) VALUES(?,?,?,?,?,?)', [
-        Number(msg.id), msg.message_id, msg.channel || 'agents', msg.sender_label || '', msg.body || '', metadata,
+        Number(local.id), local.message_id, local.channel || 'agents', local.sender_label || '', local.body || '', metadata,
       ]);
     } catch {}
   }
+  await tryStoreEmbeddings(db, local, metadata);
 }
 
 async function syncRoom(config, file, roomId, limit = 500) {
@@ -407,29 +700,73 @@ async function syncRoom(config, file, roomId, limit = 500) {
   try {
     const after = Number(getMeta(cap.db, 'last_message_id', '0')) || 0;
     const data = await apiAsAgent(config, 'GET', `/v1/rooms/${roomId}/messages?after=${encodeURIComponent(after)}&limit=${encodeURIComponent(limit)}`);
-    for (const msg of data.messages || []) insertLocalMessage(cap.db, { ...msg, room_id: roomId });
+    for (const msg of data.messages || []) await insertLocalMessage(cap.db, { ...msg, room_id: roomId }, config, roomId);
+    const embedding = await embedMissingMessages(cap.db, 500);
     setMeta(cap.db, 'last_message_id', String(data.next_after || after));
     setMeta(cap.db, 'last_sync_at', nowIso());
     saveChatDb(cap);
-    return { room_id: roomId, pulled: (data.messages || []).length, last_message_id: Number(data.next_after || after), db: cap.dbPath };
+    return { room_id: roomId, pulled: (data.messages || []).length, last_message_id: Number(data.next_after || after), db: cap.dbPath, embedding };
   } finally {
     cap.db.close();
   }
 }
 
+async function doRoomCreate(config, file, opts) {
+  const data = await apiAsAgent(config, 'POST', '/v1/rooms', {
+    title: requireValue(opts, 'title'),
+    goal: requireValue(opts, 'goal'),
+    slug: opts.slug,
+  });
+  const roomId = data.room_id || data.id;
+  storeRoomKey(config, roomId, newRoomKey());
+  saveConfig(config, file);
+  return { ...data, encrypted: true, room_key_saved: true };
+}
+
+async function doRoomInvite(config, opts) {
+  const roomId = requireValue(opts, 'room');
+  const roomKey = ensureRoomKey(config, roomId);
+  const data = await apiAsAgent(config, 'POST', `/v1/rooms/${roomId}/invites`, {
+    role: opts.role || 'member',
+    ttl_seconds: opts.ttl || opts.ttl_seconds || 86400,
+  });
+  return { ...data, private_invite: makePrivateInvite(data.invite_token, roomKey) };
+}
+
+async function doRoomJoin(config, file, opts) {
+  const parsed = parsePrivateInvite(requireValue(opts, 'invite'));
+  const data = await apiAsAgent(config, 'POST', '/v1/invites/accept', {
+    token: parsed.token,
+    fingerprint: config.agentFingerprint,
+  });
+  if (parsed.roomKey) {
+    storeRoomKey(config, data.room_id || data.workspace_id, parsed.roomKey);
+    saveConfig(config, file);
+  }
+  return { ...data, room_key_saved: Boolean(parsed.roomKey), encrypted: Boolean(parsed.roomKey) };
+}
+
 async function doChatSend(config, file, opts) {
   const roomId = requireValue(opts, 'room');
-  const body = requireValue(opts, 'text');
+  const text = requireValue(opts, 'text');
   const channel = String(opts.channel || 'agents');
+  const kind = String(opts.kind || 'chat.message');
+  const encrypted = encryptForRoom(config, roomId, {
+    text,
+    channel,
+    kind,
+    metadata: { client: 'supercollab-cli', private: true },
+    sent_at: nowIso(),
+  });
   const data = await apiAsAgent(config, 'POST', `/v1/rooms/${roomId}/messages`, {
-    body,
+    body: encrypted.encoded,
     channel,
-    kind: String(opts.kind || 'chat.message'),
-    metadata: { client: 'supercollab-cli', cwd: process.cwd() },
+    kind,
+    metadata: { encrypted: true, private: true, alg: 'A256GCM', local_search: true },
   });
   const cap = await openChatDb(config, file, roomId);
   try {
-    insertLocalMessage(cap.db, { ...data.message, room_id: roomId });
+    await insertLocalMessage(cap.db, { ...data.message, room_id: roomId }, config, roomId);
     setMeta(cap.db, 'last_message_id', String(Math.max(Number(getMeta(cap.db, 'last_message_id', '0')) || 0, Number(data.message.id))));
     saveChatDb(cap);
   } finally {
@@ -458,33 +795,106 @@ function ftsQuery(value) {
 async function doChatSearch(config, file, opts) {
   const roomId = requireValue(opts, 'room');
   const query = requireValue(opts, 'query');
+  const mode = String(opts.mode || 'hybrid').toLowerCase();
+  if (!['hybrid', 'keyword', 'vector'].includes(mode)) throw new Error('search --mode must be hybrid, keyword, or vector');
   await syncRoom(config, file, roomId, 500);
   const cap = await openChatDb(config, file, roomId);
   try {
-    let rows = [];
-    if (getMeta(cap.db, 'fts5', '0') === '1') {
+    const embedding = await embedMissingMessages(cap.db, 500);
+    const maxResults = Math.max(1, Math.min(Number(opts.limit || 20), 100));
+    let keywordRows = [];
+    if (mode !== 'vector' && getMeta(cap.db, 'fts5', '0') === '1') {
       const q = ftsQuery(query);
       if (q) {
         try {
-          rows = dbAll(
+          keywordRows = dbAll(
             cap.db,
             `SELECT m.*, bm25(messages_fts) AS score
              FROM messages_fts JOIN messages m ON m.id=messages_fts.rowid
              WHERE messages_fts MATCH ?
              ORDER BY score LIMIT ?`,
-            [q, Math.max(1, Math.min(Number(opts.limit || 20), 100))],
+            [q, maxResults],
           );
         } catch {
-          rows = [];
+          keywordRows = [];
         }
       }
     }
-    if (!rows.length) {
-      rows = dbAll(cap.db, 'SELECT *, 0 AS score FROM messages WHERE body LIKE ? OR metadata LIKE ? ORDER BY id DESC LIMIT ?', [
-        `%${query}%`, `%${query}%`, Math.max(1, Math.min(Number(opts.limit || 20), 100)),
-      ]);
+    if (mode !== 'vector' && !keywordRows.length) {
+      keywordRows = dbAll(cap.db, 'SELECT *, 0 AS score FROM messages WHERE body LIKE ? OR metadata LIKE ? ORDER BY id DESC LIMIT ?', [
+        `%${query}%`, `%${query}%`, maxResults,
+      ]).map((row) => ({ ...row, keyword_fallback: true }));
+    }
+    let vectorRows = [];
+    let vectorError = null;
+    if (mode !== 'keyword') try {
+      const qvec = await embedText(query, { isQuery: true });
+      const bestByMessage = new Map();
+      for (const row of dbAll(
+        cap.db,
+        `SELECT m.*, e.vector, e.seq, e.pos
+         FROM message_embeddings e JOIN messages m ON m.message_id=e.message_id
+         WHERE e.profile=?
+         ORDER BY m.id DESC LIMIT 3000`,
+        [EMBEDDING_PROFILE.id],
+      )) {
+        let score = 0;
+        try { score = cosine(qvec, JSON.parse(row.vector)); } catch {}
+        if (score <= 0) continue;
+        const { vector, ...clean } = row;
+        const prior = bestByMessage.get(row.message_id);
+        if (!prior || score > prior.vector_score) {
+          bestByMessage.set(row.message_id, { ...clean, vector_score: score, chunk_seq: Number(row.seq || 0), chunk_pos: Number(row.pos || 0) });
+        }
+      }
+      vectorRows = Array.from(bestByMessage.values())
+        .sort((a, b) => b.vector_score - a.vector_score)
+        .slice(0, mode === 'vector' ? maxResults : Math.max(maxResults, 50));
+    } catch (err) {
+      vectorError = err.message || String(err);
+      setMeta(cap.db, 'embedding_last_error', vectorError);
     }
-    return { room_id: roomId, query, results: rows };
+    const keywordRank = new Map(keywordRows.map((row, idx) => [row.message_id, idx + 1]));
+    const vectorRank = new Map(vectorRows.map((row, idx) => [row.message_id, idx + 1]));
+    const byMessage = new Map();
+    for (const row of [...keywordRows, ...vectorRows]) {
+      const existing = byMessage.get(row.message_id) || {};
+      byMessage.set(row.message_id, { ...existing, ...row });
+    }
+    const rrfK = 60;
+    const hybridRows = Array.from(byMessage.values()).map((row) => {
+      const kr = keywordRank.get(row.message_id);
+      const vr = vectorRank.get(row.message_id);
+      const keywordScore = kr ? 1 / (rrfK + kr) : 0;
+      const vectorScore = vr ? 1 / (rrfK + vr) : 0;
+      return {
+        ...row,
+        search_sources: [kr ? (row.keyword_fallback ? 'like' : 'fts5_bm25') : null, vr ? 'bge_vector_cosine' : null].filter(Boolean),
+        keyword_rank: kr || null,
+        vector_rank: vr || null,
+        hybrid_score: keywordScore + vectorScore,
+      };
+    }).sort((a, b) => b.hybrid_score - a.hybrid_score).slice(0, maxResults);
+    const results = mode === 'keyword'
+      ? keywordRows.slice(0, maxResults).map((row, idx) => ({ ...row, search_sources: [row.keyword_fallback ? 'like' : 'fts5_bm25'], keyword_rank: idx + 1 }))
+      : mode === 'vector'
+        ? vectorRows.slice(0, maxResults).map((row, idx) => ({ ...row, search_sources: ['bge_vector_cosine'], vector_rank: idx + 1 }))
+        : hybridRows;
+    return {
+      room_id: roomId,
+      query,
+      search: {
+        local_only: true,
+        mode,
+        methods: ['fts5_bm25', 'bge_vector_cosine', 'rrf_hybrid'],
+        fts: getMeta(cap.db, 'fts5', '0') === '1',
+        vector: EMBEDDING_PROFILE.id,
+        embedding_profile: EMBEDDING_PROFILE,
+        embedding,
+        vector_error: vectorError,
+      },
+      results,
+    };
   } finally {
     cap.db.close();
   }
@@ -516,6 +926,7 @@ function agentInstructions(active) {
 
 function activate(config, file, opts) {
   const roomId = requireValue(opts, 'room');
+  ensureRoomKey(config, roomId);
   const cwd = normalizeCwd(opts.cwd);
   config.activations = config.activations || {};
   config.activations[cwd] = { roomId, enabled: true, activatedAt: nowIso() };
@@ -542,6 +953,7 @@ async function activeStatus(config, file, opts = {}) {
     room_id: active?.roomId || null,
     activation_root: active?.cwd || null,
     config: file,
+    embedding_profile: EMBEDDING_PROFILE,
     instructions: agentInstructions(active),
   };
 }
@@ -569,7 +981,7 @@ function mcpTools() {
     toolSchema('room_join', 'Accept a room invite token.', { invite_token: s, fingerprint: s }, ['invite_token']),
     toolSchema('chat_send', 'Send a message to the active agent chat room.', { text: s, channel: s, kind: s }, ['text']),
     toolSchema('chat_read', 'Sync and read recent messages from the active room.', { limit: { type: 'integer' } }),
-    toolSchema('chat_search', 'Sync and search the active room transcript.', { query: s, limit: { type: 'integer' } }, ['query']),
+    toolSchema('chat_search', 'Sync and search the active room transcript with local keyword, BGE vector, or hybrid retrieval.', { query: s, mode: s, limit: { type: 'integer' } }, ['query']),
     toolSchema('chat_sync', 'Sync the active room transcript into local SQLite.'),
   ];
 }
@@ -578,12 +990,12 @@ async function callTool(config, name, args) {
   const file = config.__configFile || DEFAULT_CONFIG;
   if (name === 'supercollab_status') return activeStatus(config, file, {});
   if (name === 'room_list') return apiAsAgent(config, 'GET', '/v1/rooms');
-  if (name === 'room_create') return apiAsAgent(config, 'POST', '/v1/rooms', { title: args.title, goal: args.goal, slug: args.slug });
-  if (name === 'room_invite') return apiAsAgent(config, 'POST', `/v1/rooms/${args.room_id}/invites`, { role: args.role || 'member', ttl_seconds: args.ttl_seconds || 86400 });
-  if (name === 'room_join') return apiAsAgent(config, 'POST', '/v1/invites/accept', { token: args.invite_token, fingerprint: args.fingerprint || config.agentFingerprint });
+  if (name === 'room_create') return doRoomCreate(config, file, { title: args.title, goal: args.goal, slug: args.slug });
+  if (name === 'room_invite') return doRoomInvite(config, { room: args.room_id, role: args.role || 'member', ttl_seconds: args.ttl_seconds || 86400 });
+  if (name === 'room_join') return doRoomJoin(config, file, { invite: args.invite_token });
   if (name === 'chat_send') return doChatSend(config, file, { room: requireActiveRoom(config, args), text: args.text, channel: args.channel || 'agents', kind: args.kind || 'chat.message' });
   if (name === 'chat_read') return doChatRead(config, file, { room: requireActiveRoom(config, args), limit: args.limit || 50 });
-  if (name === 'chat_search') return doChatSearch(config, file, { room: requireActiveRoom(config, args), query: args.query, limit: args.limit || 20 });
+  if (name === 'chat_search') return doChatSearch(config, file, { room: requireActiveRoom(config, args), query: args.query, mode: args.mode || 'hybrid', limit: args.limit || 20 });
   if (name === 'chat_sync') return syncRoom(config, file, requireActiveRoom(config, args));
   throw new Error(`unknown tool: ${name}`);
 }
@@ -663,6 +1075,24 @@ function printCodexConfig(opts) {
   console.log(`[mcp_servers.supercollab]\ncommand = "supercollab"\nargs = ["mcp", "stdio", "--config", "${file.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"]`);
 }
 
+async function embeddingStatus() {
+  return {
+    ok: true,
+    profile: EMBEDDING_PROFILE,
+    model_download: 'lazy on first embedding, or now via `supercollab embeddings warmup`',
+    cache_dir: process.env.SUPERCOLLAB_MODEL_CACHE || 'default @huggingface/transformers cache',
+  };
+}
+
+async function embeddingWarmup() {
+  const vector = await embedText('supercollab embedding warmup', { isQuery: true });
+  return {
+    ok: true,
+    dims: vector.length,
+    profile: EMBEDDING_PROFILE,
+  };
+}
+
 async function main() {
   const { positionals, opts } = parse(process.argv.slice(2));
   if (opts.help || positionals.length === 0) { printHelp(); return; }
@@ -682,10 +1112,11 @@ async function main() {
   }
   if (cmd === 'room') {
     if (sub === 'list') return console.log(JSON.stringify(await apiAsAgent(config, 'GET', '/v1/rooms'), null, 2));
-    if (sub === 'create') return console.log(JSON.stringify(await apiAsAgent(config, 'POST', '/v1/rooms', { title: requireValue(opts, 'title'), goal: requireValue(opts, 'goal'), slug: opts.slug }), null, 2));
-    if (sub === 'invite') return console.log(JSON.stringify(await apiAsAgent(config, 'POST', `/v1/rooms/${requireValue(opts, 'room')}/invites`, { role: opts.role || 'member', ttl_seconds: opts.ttl || 86400 }), null, 2));
+    if (sub === 'create') return console.log(JSON.stringify(await doRoomCreate(config, file, opts), null, 2));
+    if (sub === 'invite') return console.log(JSON.stringify(await doRoomInvite(config, opts), null, 2));
     if (sub === 'invites') return console.log(JSON.stringify(await apiAsAgent(config, 'GET', `/v1/rooms/${requireValue(opts, 'room')}/invites`), null, 2));
-    if (sub === 'join') return console.log(JSON.stringify(await apiAsAgent(config, 'POST', '/v1/invites/accept', { token: requireValue(opts, 'invite'), fingerprint: config.agentFingerprint }), null, 2));
+    if (sub === 'join') return console.log(JSON.stringify(await doRoomJoin(config, file, opts), null, 2));
+    if (sub === 'key') return console.log(ensureRoomKey(config, requireValue(opts, 'room')));
   }
   if (cmd === 'chat') {
     if (sub === 'send') return console.log(JSON.stringify(await doChatSend(config, file, opts), null, 2));
@@ -700,6 +1131,10 @@ async function main() {
     if (sub === 'list') return console.log(JSON.stringify(await api(config, 'GET', '/v1/agent-sessions', undefined, config.userToken), null, 2));
     if (sub === 'revoke') return console.log(JSON.stringify(await api(config, 'DELETE', `/v1/agent-sessions/${requireValue(opts, 'session')}`, undefined, config.userToken), null, 2));
   }
+  if (cmd === 'embeddings') {
+    if (sub === 'status') return console.log(JSON.stringify(await embeddingStatus(), null, 2));
+    if (sub === 'warmup') return console.log(JSON.stringify(await embeddingWarmup(), null, 2));
+  }
   if (cmd === 'mcp' && sub === 'stdio') return runMcp(opts);
   if (cmd === 'mcp' && sub === 'print-config') return printCodexConfig(opts);
   throw new Error(`unknown command: ${positionals.join(' ')}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@supercollab/cli",
-  "version": "0.3.0",
-  "description": "SuperCollab CLI and MCP bridge for secure agent group chat.",
+  "version": "0.4.1",
+  "description": "SuperCollab CLI and MCP bridge for encrypted local-search agent group chat.",
   "type": "module",
   "bin": {
     "supercollab": "./bin/supercollab.js"
@@ -14,6 +14,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@huggingface/transformers": "3.8.1",
     "sql.js": "^1.14.1"
   },
   "keywords": [