Brainstorm Companion

Waiting for the agent to push a screen...

`); } const FORBIDDEN_PAGE = ` Session key required

Session key required

This page needs the full URL your coding agent gave you, including the ?key=… part. Copy the complete URL and open it again.

`; function bootstrapPage(key) { const jsonKey = JSON.stringify(String(key)); return ` Opening Brainstorm Companion `; } const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8'); const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8'); const helperInjection = ''; // ========== Helper Functions ========== function readSuperpowersVersion() { const root = path.join(__dirname, '../../..'); const manifests = [ path.join(root, 'package.json'), path.join(root, '.codex-plugin/plugin.json') ]; for (const manifest of manifests) { try { const data = JSON.parse(fs.readFileSync(manifest, 'utf-8')); if (data.version) return String(data.version); } catch (e) { // Packaged Codex plugins omit package.json; try the next manifest. } } return 'unknown'; } function isTruthyEnv(value) { if (!value) return false; const normalized = String(value).trim().toLowerCase(); if (!normalized) return false; return !['0', 'false', 'no', 'off'].includes(normalized); } function escapeHtmlText(value) { return String(value) .replace(/&/g, '&') .replace(//g, '>') .replace(/"/g, '"'); } function brandMarkup() { const version = escapeHtmlText(SUPERPOWERS_VERSION); const text = SUPERPOWERS_TELEMETRY_DISABLED ? 'Prime Radiant Superpowers v' + version : 'Superpowers v' + version; const logo = SUPERPOWERS_TELEMETRY_DISABLED ? '' : '

'; return '

' + logo + '' + text + '

'; } function renderBranding(html) { return html.split('').join(brandMarkup()); } function isFullDocument(html) { const trimmed = html.trimStart().toLowerCase(); return trimmed.startsWith('', content); } function getNewestScreen() { const files = fs.readdirSync(CONTENT_DIR) .filter(f => !f.startsWith('.') && f.endsWith('.html')) .map(f => { const fp = path.join(CONTENT_DIR, f); if (!isRegularFileInsideContentDir(fp)) return null; return { path: fp, mtime: fs.statSync(fp).mtime.getTime() }; }) .filter(Boolean) .sort((a, b) => b.mtime - a.mtime); return files.length > 0 ? files[0].path : null; } function urlHostForHttp(host) { const h = String(host); if (h.startsWith('[') && h.endsWith(']')) return h; return h.includes(':') ? '[' + h + ']' : h; } function companionUrl() { return 'http://' + urlHostForHttp(URL_HOST) + ':' + PORT + '/?key=' + TOKEN; } function browserLauncherForPlatform(url, { platform = process.platform, osRelease = require('os').release(), env = process.env } = {}) { const isWSL = platform === 'linux' && /microsoft/i.test(osRelease); if (platform === 'darwin') return { bin: 'open', args: [url] }; if (platform === 'win32' || isWSL) { return { bin: 'rundll32.exe', args: ['url.dll,FileProtocolHandler', url] }; } if (env.DISPLAY || env.WAYLAND_DISPLAY) return { bin: 'xdg-open', args: [url] }; return null; } function isRegularFileInsideContentDir(filePath) { let stat, realContentDir, realFilePath; try { stat = fs.lstatSync(filePath); if (stat.isSymbolicLink()) return false; if (!stat.isFile()) return false; if (stat.nlink !== 1) return false; realContentDir = fs.realpathSync(CONTENT_DIR); realFilePath = fs.realpathSync(filePath); } catch (e) { return false; } return realFilePath.startsWith(realContentDir + path.sep); } // ========== Authentication ========== function timingSafeEqualStr(a, b) { const ab = Buffer.from(String(a)); const bb = Buffer.from(String(b)); if (ab.length !== bb.length) return false; return crypto.timingSafeEqual(ab, bb); } function parseCookies(header) { const out = {}; if (!header) return out; for (const part of header.split(';')) { const eq = part.indexOf('='); if (eq < 0) continue; out[part.slice(0, eq).trim()] = part.slice(eq + 1).trim(); } return out; } // A request is authorized if it carries the session key as ?key= or as the // session cookie. Both are compared in constant time. function isAuthorized(req) { const q = req.url.indexOf('?'); if (q >= 0) { const params = new URLSearchParams(req.url.slice(q + 1)); if (params.has('key')) { const key = params.get('key'); return Boolean(key && timingSafeEqualStr(key, TOKEN)); } } const cookie = parseCookies(req.headers['cookie'])[COOKIE_NAME]; if (cookie && timingSafeEqualStr(cookie, TOKEN)) return true; return false; } function pathnameOf(url) { const q = url.indexOf('?'); return q >= 0 ? url.slice(0, q) : url; } function queryKey(url) { const q = url.indexOf('?'); if (q < 0) return null; return new URLSearchParams(url.slice(q + 1)).get('key'); } function securityHeaders(headers = {}) { return { 'Referrer-Policy': 'no-referrer', 'Cache-Control': 'no-store', 'X-Frame-Options': 'DENY', 'Content-Security-Policy': "frame-ancestors 'none'", 'Cross-Origin-Resource-Policy': 'same-origin', ...headers }; } function isAllowedWebSocketOrigin(req) { const origin = req.headers.origin; if (!origin) return true; const host = req.headers.host; if (!host) return false; return origin === 'http://' + host; } // ========== HTTP Request Handler ========== function handleRequest(req, res) { if (!isAuthorized(req)) { res.writeHead(403, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' })); res.end(FORBIDDEN_PAGE); return; } touchActivity(); // only authorized requests count as activity // Mirror the key into a cookie so same-origin subresources (/files/*) can // authenticate after bootstrap. HttpOnly keeps it away from page scripts; the // WebSocket Origin check below is what blocks cross-origin localhost injection. res.setHeader('Set-Cookie', COOKIE_NAME + '=' + TOKEN + '; HttpOnly; SameSite=Strict; Path=/'); const pathname = pathnameOf(req.url); const keyFromQuery = queryKey(req.url); if (req.method === 'GET' && pathname === '/' && keyFromQuery && timingSafeEqualStr(keyFromQuery, TOKEN)) { res.writeHead(200, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' })); res.end(bootstrapPage(keyFromQuery)); } else if (req.method === 'GET' && pathname === '/') { const screenFile = getNewestScreen(); let html = screenFile ? (raw => isFullDocument(raw) ? raw : wrapInFrame(raw))(fs.readFileSync(screenFile, 'utf-8')) : waitingPage(); if (html.includes('')) { html = html.replace('', helperInjection + '\n'); } else { html += helperInjection; } res.writeHead(200, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' })); res.end(html); } else if (req.method === 'GET' && pathname.startsWith('/files/')) { const fileName = path.basename(pathname.slice(7)); const filePath = path.join(CONTENT_DIR, fileName); // Reject empty/dotfile names and anything that isn't a regular file — // `/files/` would otherwise resolve to CONTENT_DIR and crash readFileSync (EISDIR). if (!fileName || fileName.startsWith('.') || !isRegularFileInsideContentDir(filePath)) { res.writeHead(404, securityHeaders()); res.end('Not found'); return; } const ext = path.extname(filePath).toLowerCase(); const contentType = MIME_TYPES[ext] || 'application/octet-stream'; res.writeHead(200, securityHeaders({ 'Content-Type': contentType })); res.end(fs.readFileSync(filePath)); } else { res.writeHead(404, securityHeaders()); res.end('Not found'); } } // ========== WebSocket Connection Handling ========== const clients = new Set(); function handleUpgrade(req, socket) { if (!isAuthorized(req) || !isAllowedWebSocketOrigin(req)) { socket.destroy(); return; } const key = req.headers['sec-websocket-key']; if (!key) { socket.destroy(); return; } const accept = computeAcceptKey(key); socket.write( 'HTTP/1.1 101 Switching Protocols\r\n' + 'Upgrade: websocket\r\n' + 'Connection: Upgrade\r\n' + 'Sec-WebSocket-Accept: ' + accept + '\r\n\r\n' ); let buffer = Buffer.alloc(0); clients.add(socket); socket.on('data', (chunk) => { buffer = Buffer.concat([buffer, chunk]); while (buffer.length > 0) { let result; try { result = decodeFrame(buffer); } catch (e) { socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0))); clients.delete(socket); return; } if (!result) break; buffer = buffer.slice(result.bytesConsumed); switch (result.opcode) { case OPCODES.TEXT: handleMessage(result.payload.toString()); break; case OPCODES.CLOSE: socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0))); clients.delete(socket); return; case OPCODES.PING: socket.write(encodeFrame(OPCODES.PONG, result.payload)); break; case OPCODES.PONG: break; default: { const closeBuf = Buffer.alloc(2); closeBuf.writeUInt16BE(1003); socket.end(encodeFrame(OPCODES.CLOSE, closeBuf)); clients.delete(socket); return; } } } }); socket.on('close', () => clients.delete(socket)); socket.on('error', () => clients.delete(socket)); } function handleMessage(text) { let event; try { event = JSON.parse(text); } catch (e) { console.error('Failed to parse WebSocket message:', e.message); return; } touchActivity(); console.log(JSON.stringify({ source: 'user-event', ...event })); if (event && event.choice) { const eventsFile = path.join(STATE_DIR, 'events'); fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n'); } } function broadcast(msg) { const frame = encodeFrame(OPCODES.TEXT, Buffer.from(JSON.stringify(msg))); for (const socket of clients) { try { socket.write(frame); } catch (e) { clients.delete(socket); } } } // Best-effort: open the user's browser the first time a screen is actually ready // to show. Skips when disabled, on a non-loopback (remote) bind, or when a // browser is already connected. Override the launcher with BRAINSTORM_OPEN_CMD. let browserOpened = false; function maybeOpenBrowser() { if (browserOpened) return; browserOpened = true; if (!process.env.BRAINSTORM_OPEN) return; // opt-in: only after the user approves the companion if (HOST !== '127.0.0.1' && HOST !== 'localhost') return; if (clients.size > 0) return; // the user already opened it const url = companionUrl(); // must carry the key or the gate 403s it const cp = require('child_process'); // Operator-provided launcher: run as given (this env var is trusted operator input). if (process.env.BRAINSTORM_OPEN_CMD) { try { cp.exec(process.env.BRAINSTORM_OPEN_CMD + ' ' + JSON.stringify(url), () => {}); } catch (e) { /* best effort */ } return; } // Platform launchers: pass the URL as an argv element via execFile (no shell), // so a url-host containing shell metacharacters can't inject a command. const launcher = browserLauncherForPlatform(url); if (!launcher) return; // headless: nothing to open try { cp.execFile(launcher.bin, launcher.args, () => {}); } catch (e) { /* best effort */ } } // ========== Activity Tracking ========== // Idle timeout: shut down after this long with no activity. Default 4 hours; // override with BRAINSTORM_IDLE_TIMEOUT_MS (start-server.sh: --idle-timeout-minutes). const IDLE_TIMEOUT_MS = (() => { const ms = Number(process.env.BRAINSTORM_IDLE_TIMEOUT_MS); return Number.isFinite(ms) && ms > 0 ? ms : 4 * 60 * 60 * 1000; })(); // How often the watchdog checks for owner-death / idleness. Configurable mainly // so tests can run fast; production default is 60s. const LIFECYCLE_CHECK_MS = (() => { const ms = Number(process.env.BRAINSTORM_LIFECYCLE_CHECK_MS); return Number.isFinite(ms) && ms > 0 ? ms : 60 * 1000; })(); let lastActivity = Date.now(); function touchActivity() { lastActivity = Date.now(); } // ========== File Watching ========== const debounceTimers = new Map(); // ========== Server Startup ========== function startServer() { if (!fs.existsSync(CONTENT_DIR)) fs.mkdirSync(CONTENT_DIR, { recursive: true }); if (!fs.existsSync(STATE_DIR)) fs.mkdirSync(STATE_DIR, { recursive: true }); // Track known files to distinguish new screens from updates. // macOS fs.watch reports 'rename' for both new files and overwrites, // so we can't rely on eventType alone. const knownFiles = new Set( fs.readdirSync(CONTENT_DIR).filter(f => !f.startsWith('.') && f.endsWith('.html')) ); const server = http.createServer(handleRequest); server.on('upgrade', handleUpgrade); const watcher = fs.watch(CONTENT_DIR, (eventType, filename) => { if (!filename || filename.startsWith('.') || !filename.endsWith('.html')) return; if (debounceTimers.has(filename)) clearTimeout(debounceTimers.get(filename)); debounceTimers.set(filename, setTimeout(() => { debounceTimers.delete(filename); const filePath = path.join(CONTENT_DIR, filename); if (!fs.existsSync(filePath)) return; // file was deleted touchActivity(); if (!knownFiles.has(filename)) { knownFiles.add(filename); const eventsFile = path.join(STATE_DIR, 'events'); if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile); console.log(JSON.stringify({ type: 'screen-added', file: filePath })); maybeOpenBrowser(); } else { console.log(JSON.stringify({ type: 'screen-updated', file: filePath })); } broadcast({ type: 'reload' }); }, 100)); }); watcher.on('error', (err) => console.error('fs.watch error:', err.message)); function shutdown(reason) { console.log(JSON.stringify({ type: 'server-stopped', reason })); const infoFile = path.join(STATE_DIR, 'server-info'); if (fs.existsSync(infoFile)) fs.unlinkSync(infoFile); fs.writeFileSync( path.join(STATE_DIR, 'server-stopped'), JSON.stringify({ reason, timestamp: Date.now() }) + '\n' ); watcher.close(); clearInterval(lifecycleCheck); // Close any upgraded WebSocket sockets so server.close() can complete and // the process actually exits instead of lingering on an open connection. for (const socket of clients) { try { socket.destroy(); } catch (e) { /* already gone */ } } server.close(() => process.exit(0)); } function ownerAlive() { if (!ownerPid) return true; try { process.kill(ownerPid, 0); return true; } catch (e) { return e.code === 'EPERM'; } } // Periodically exit if the owner process died or we've been idle too long. const lifecycleCheck = setInterval(() => { if (!ownerAlive()) shutdown('owner process exited'); else if (Date.now() - lastActivity > IDLE_TIMEOUT_MS) shutdown('idle timeout'); }, LIFECYCLE_CHECK_MS); lifecycleCheck.unref(); // Validate owner PID at startup. If it's already dead, the PID resolution // was wrong (common on WSL, Tailscale SSH, and cross-user scenarios). // Disable monitoring and rely on the idle timeout instead. if (ownerPid) { try { process.kill(ownerPid, 0); } catch (e) { if (e.code !== 'EPERM') { console.log(JSON.stringify({ type: 'owner-pid-invalid', pid: ownerPid, reason: 'dead at startup' })); ownerPid = null; } } } // If the preferred port is already taken (e.g. a previous server is still // alive), fall back to a random port once instead of failing. let triedFallback = false; function onListen() { // Cookie name keys on the ACTUAL bound port (may differ from the preferred // one after an EADDRINUSE fallback) so it can't collide with another server's // cookie in the shared localhost jar. COOKIE_NAME = 'brainstorm-key-' + PORT; // Record the bound port AND token so the next restart of this session reuses // them — but ONLY when we got our preferred port. On a fallback we bound a // *different* port because someone else holds the preferred one; persisting // would overwrite the shared files and strand that other session's open tab. if (PORT_FILE && !triedFallback) { try { fs.writeFileSync(PORT_FILE, String(PORT)); } catch (e) { /* best effort */ } if (TOKEN_FILE) { try { fs.writeFileSync(TOKEN_FILE, TOKEN, { mode: 0o600 }); chmodOwnerOnly(TOKEN_FILE); } catch (e) { /* best effort */ } } } const info = JSON.stringify({ type: 'server-started', port: Number(PORT), host: HOST, url_host: URL_HOST, url: companionUrl(), screen_dir: CONTENT_DIR, state_dir: STATE_DIR, idle_timeout_ms: IDLE_TIMEOUT_MS }); console.log(info); // server-info embeds the key — keep it owner-only. fs.writeFileSync(path.join(STATE_DIR, 'server-info'), info + '\n', { mode: 0o600 }); } server.on('error', (err) => { if (err.code === 'EADDRINUSE' && !triedFallback) { if (tokenSource === 'env') { console.error('Server failed to bind: preferred port is in use and BRAINSTORM_TOKEN is set; refusing fallback with explicit token'); process.exit(1); } triedFallback = true; PORT = randomPort(); if (tokenSource === 'file') { TOKEN = generateToken(); tokenSource = 'generated-fallback'; } server.listen(PORT, HOST, onListen); } else { console.error('Server failed to bind:', err.message); process.exit(1); } }); server.listen(PORT, HOST, onListen); } if (require.main === module) { startServer(); } module.exports = { computeAcceptKey, encodeFrame, decodeFrame, browserLauncherForPlatform, OPCODES, MAX_FRAME_PAYLOAD_BYTES };

brainstorming

Install this skill

Comments