pikiloop 0.4.0

package/dist/agent/mcp/bridge.js

@@ -0,0 +1,791 @@
+/**
+ * mcp-bridge.ts — MCP session bridge orchestrator.
+ *
+ * Runs inside the main pikiloop process. For each agent stream:
+ *   1. Starts a tiny HTTP callback server on localhost (random port).
+ *   2. Writes an MCP config JSON pointing to `pikiloop --mcp-serve`.
+ *   3. The agent CLI loads that config via its MCP registration mechanism.
+ *   4. When the agent calls `send_file`, the MCP server POSTs to our callback.
+ *   5. We forward the request to the IM channel and respond with success/failure.
+ *
+ * Lifecycle: one bridge per stream, created before spawn, stopped after stream ends.
+ */
+import http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile, spawnSync } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { ensurePlaywrightMcpConfigFile, getConfiguredRemoteCdpUrl, getManagedBrowserProfileDir, resolveManagedBrowserCdpEndpoint, resolveManagedBrowserMcpCommand, } from '../../browser-profile.js';
+import { loadUserConfig } from '../../core/config/user-config.js';
+import { MCP_TIMEOUTS, MCP_ARTIFACT_MAX_BYTES } from '../../core/constants.js';
+import { mergeExtensionsForSession, getGlobalExtensionsAsServers } from './extensions.js';
+function sanitizeExecArgv(execArgv) {
+    return execArgv.filter(arg => !/^--inspect(?:-brk)?(?:=.*)?$/.test(arg));
+}
+function resolveCurrentCliCommand(runtime, extraArgs) {
+    const entryScript = runtime.argv[1] ? path.resolve(runtime.argv[1]) : '';
+    const base = path.basename(entryScript).toLowerCase();
+    if (!entryScript || !fs.existsSync(entryScript))
+        return null;
+    if (base !== 'main.js' && base !== 'main.ts' && base !== 'cli.js' && base !== 'cli.ts')
+        return null;
+    return {
+        command: runtime.execPath,
+        args: [...sanitizeExecArgv(runtime.execArgv), entryScript, ...extraArgs],
+    };
+}
+export function resolveMcpServerCommand(runtime = {
+    execPath: process.execPath,
+    execArgv: process.execArgv,
+    argv: process.argv,
+    moduleUrl: import.meta.url,
+}) {
+    const currentProcess = resolveCurrentCliCommand(runtime, ['--mcp-serve']);
+    if (currentProcess)
+        return currentProcess;
+    // Try to find the compiled JS file in the same directory as this module
+    const thisDir = path.dirname(fileURLToPath(runtime.moduleUrl));
+    const serverScript = path.join(thisDir, 'session-server.js');
+    if (fs.existsSync(serverScript)) {
+        return { command: 'node', args: [serverScript] };
+    }
+    // Fallback: use pikiloop CLI with --mcp-serve flag
+    const cliScript = path.resolve(thisDir, '../../cli/main.js');
+    if (fs.existsSync(cliScript)) {
+        return { command: 'node', args: [cliScript, '--mcp-serve'] };
+    }
+    // Last resort: assume pikiloop is in PATH
+    return { command: 'pikiloop', args: ['--mcp-serve'] };
+}
+function parseOptionalBool(value) {
+    if (typeof value === 'boolean')
+        return value;
+    const text = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    if (!text)
+        return null;
+    if (['1', 'true', 'yes', 'on'].includes(text))
+        return true;
+    if (['0', 'false', 'no', 'off'].includes(text))
+        return false;
+    return null;
+}
+function boolFromConfigEnv(configValue, envValue, fallback) {
+    const envParsed = parseOptionalBool(envValue);
+    if (envParsed != null)
+        return envParsed;
+    const configParsed = parseOptionalBool(configValue);
+    if (configParsed != null)
+        return configParsed;
+    return fallback;
+}
+export function resolveGuiIntegrationConfig(config = loadUserConfig(), env = process.env) {
+    // A configured remote CDP endpoint implies the user wants browser automation,
+    // so it flips the *default* on. An explicit PIKILOOP_BROWSER_ENABLED / config
+    // value still wins (so `=false` can disable even with a CDP URL set). This
+    // removes the footgun where setting only PIKILOOP_BROWSER_CDP_URL silently
+    // injected no browser server at all.
+    const browserEnabled = boolFromConfigEnv(typeof config.browserEnabled === 'boolean' ? config.browserEnabled : config.browserUseProfile, env.PIKILOOP_BROWSER_ENABLED ?? env.PIKILOOP_BROWSER_USE_PROFILE, !!getConfiguredRemoteCdpUrl(env));
+    const peekabooEnabled = boolFromConfigEnv(config.peekabooEnabled, env.PIKILOOP_PEEKABOO_ENABLED, false);
+    return {
+        browserEnabled,
+        browserProfileDir: getManagedBrowserProfileDir(),
+        browserHeadless: boolFromConfigEnv(config.browserHeadless, env.PIKILOOP_BROWSER_HEADLESS, false),
+        peekabooEnabled,
+    };
+}
+export function buildSupplementalMcpServers(gui = resolveGuiIntegrationConfig(), endpoints = {}) {
+    const servers = [];
+    if (gui.browserEnabled) {
+        const profileDir = gui.browserProfileDir || getManagedBrowserProfileDir();
+        const cdpEndpoint = (endpoints.cdpEndpoint || '').trim() || null;
+        const browserServer = resolveManagedBrowserMcpCommand(profileDir, {
+            headless: gui.browserHeadless,
+            cdpEndpoint,
+        });
+        servers.push({
+            name: 'pikiloop-browser',
+            command: browserServer.command,
+            args: browserServer.args,
+        });
+    }
+    if (gui.peekabooEnabled && process.platform === 'darwin') {
+        // Peekaboo — native macOS GUI automation via Accessibility + ScreenCaptureKit.
+        // Run the dedicated MCP bin from the multi-bin @steipete/peekaboo package.
+        servers.push({
+            name: 'peekaboo',
+            command: 'npx',
+            args: ['-y', '-p', '@steipete/peekaboo', 'peekaboo-mcp'],
+        });
+    }
+    return servers;
+}
+export function buildGuiSetupHints(gui = resolveGuiIntegrationConfig()) {
+    const hints = [];
+    if (gui.browserEnabled) {
+        hints.push(`managed browser profile mode enabled; runtime sessions reuse ${gui.browserProfileDir || getManagedBrowserProfileDir()}; configured MCP browser mode=${gui.browserHeadless ? 'headless' : 'headed'}. This mode keeps automation isolated from your everyday browser. If the managed browser is already open, pikiloop will try to attach to it first. When using browser_tabs, use action="new" to open a tab, not "create".`);
+    }
+    if (gui.peekabooEnabled && process.platform === 'darwin') {
+        hints.push('Peekaboo enabled — native macOS GUI tools (see / click / type / scroll / window / menu / app / dock) via Accessibility + ScreenCaptureKit. Prefer element-ID interactions (call `see` first) over raw coordinates.');
+    }
+    return hints;
+}
+function buildClaudeMcpConfig(servers) {
+    return {
+        mcpServers: Object.fromEntries(servers.map(server => [
+            server.name,
+            { type: 'stdio', command: server.command, args: server.args, ...(server.env ? { env: server.env } : {}) },
+        ])),
+    };
+}
+/**
+ * Build the `codex mcp add` argv for a single registered server. Returns
+ * `null` when the descriptor lacks the fields needed for its transport
+ * (treated as a no-op rather than throwing — keeps a malformed entry from
+ * breaking the whole session).
+ *
+ * HTTP servers can't pass a literal bearer to codex; the CLI only accepts
+ * `--bearer-token-env-var <NAME>`. We synthesize a deterministic env-var
+ * name per server, stash the token in the supplied `tokenEnv` map, and the
+ * caller threads that map into the codex child process via extraEnv.
+ *
+ * Exported for unit tests; not re-exported from the package surface.
+ */
+export function buildCodexMcpAddArgs(server, tokenEnv) {
+    if (server.type === 'http') {
+        if (!server.url)
+            return null;
+        const args = ['mcp', 'add', server.name, '--url', server.url];
+        const bearer = extractBearerToken(server.headers);
+        if (bearer) {
+            const envName = codexBearerEnvName(server.name);
+            tokenEnv[envName] = bearer;
+            args.push('--bearer-token-env-var', envName);
+        }
+        return args;
+    }
+    if (!server.command)
+        return null;
+    const args = ['mcp', 'add', server.name];
+    for (const [k, v] of Object.entries(server.env || {}))
+        args.push('--env', `${k}=${v}`);
+    args.push('--', server.command, ...(server.args || []));
+    return args;
+}
+function extractBearerToken(headers) {
+    if (!headers)
+        return null;
+    for (const [k, v] of Object.entries(headers)) {
+        if (k.toLowerCase() !== 'authorization')
+            continue;
+        const m = /^\s*Bearer\s+(.+)$/i.exec(v);
+        if (m)
+            return m[1].trim();
+    }
+    return null;
+}
+function codexBearerEnvName(serverName) {
+    const safe = serverName.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+    return `PIKILOOP_MCP_BEARER_${safe || 'UNNAMED'}`;
+}
+export function buildGeminiMcpConfig(servers) {
+    return {
+        // Session attachments live under .pikiloop/... and should remain readable to
+        // Gemini's built-in file tools even when the project ignores that directory.
+        fileFiltering: {
+            respectGitIgnore: false,
+            respectGeminiIgnore: false,
+        },
+        mcpServers: Object.fromEntries(servers.map(server => {
+            if (server.type === 'http' && server.url) {
+                return [
+                    server.name,
+                    {
+                        type: 'http',
+                        url: server.url,
+                        ...(server.headers && Object.keys(server.headers).length ? { headers: server.headers } : {}),
+                        trust: true,
+                    },
+                ];
+            }
+            return [
+                server.name,
+                {
+                    command: server.command,
+                    args: server.args || [],
+                    ...(server.env ? { env: server.env } : {}),
+                    trust: true,
+                },
+            ];
+        })),
+    };
+}
+// ---------------------------------------------------------------------------
+// Stale playwright-mcp reaper
+// ---------------------------------------------------------------------------
+/**
+ * Find and SIGTERM playwright-mcp processes that attach to the same managed
+ * Chrome CDP endpoint but are NOT descendants of the current pikiloop process.
+ *
+ * Background: playwright-mcp is spawned by the agent CLI (e.g. claude) as a
+ * child via the mcp-config we write. When the agent CLI is killed ungracefully
+ * — or worse, gets reparented to launchd/init and survives across pikiloop
+ * restarts — its playwright-mcp child stays alive too. Multiple playwright-mcp
+ * instances attached to the same `--cdp-endpoint` cause backend state
+ * confusion (microsoft/playwright-mcp#1299, #893) and manifest as
+ * `Connection closed` errors or 2+ minute hangs the next time a tool is
+ * called. The community's recommended hygiene is one playwright-mcp per
+ * agent instance; this sweeper enforces that by reaping orphans from prior
+ * runs at the start of every new bridge.
+ *
+ * Safety: a candidate is only reaped if its `ppid` chain — walked entirely in
+ * memory from a single `ps` snapshot — does NOT include the current pikiloop
+ * process. In-flight playwright-mcp children of THIS pikiloop (sibling
+ * streams) are always spared.
+ */
+/**
+ * Pure matcher for the reaper. Returns true when `command` looks like a
+ * playwright-mcp process attached to the same CDP endpoint as ours.
+ *
+ * Accepts both invocation forms we have seen in the wild:
+ *   - `node <path>/@playwright/mcp/cli.js …`   (direct, pikiloop's preferred)
+ *   - `node <path>/node_modules/.bin/playwright-mcp …`   (npm bin symlink,
+ *     used by `npx @playwright/mcp` and any agent CLI that resolves via PATH)
+ *
+ * The CDP endpoint must also appear literally in the argv — without that
+ * guard a stray `npm exec @playwright/mcp` with its own browser would be
+ * killed, and unrelated `node -e <src>` processes whose inline source happens
+ * to mention `@playwright/mcp` would also be misidentified.
+ */
+export function _matchPlaywrightMcpProcessCommand(command, normalizedCdpEndpoint) {
+    if (!command || !normalizedCdpEndpoint)
+        return false;
+    const tokens = command.split(/\s+/);
+    if (tokens.length < 2)
+        return false;
+    if (!/(?:^|[\\/])node(?:\.exe)?$/.test(tokens[0]))
+        return false;
+    const isCliJs = /@playwright[\\/]mcp[\\/]cli\.js$/.test(tokens[1]);
+    const isBinSymlink = /[\\/]\.bin[\\/]playwright-mcp(?:\.cmd)?$/.test(tokens[1]);
+    if (!isCliJs && !isBinSymlink)
+        return false;
+    if (!command.includes(normalizedCdpEndpoint))
+        return false;
+    return true;
+}
+// Promisified spawn for codex MCP registration — keeps the per-server add/remove
+// off the event loop (was execFileSync, which blocked per spawn at stream start).
+const execFileAsync = promisify(execFile);
+// Reaping shells out to a full `ps` table scan + per-line regex and only guards
+// against playwright-mcp orphans left by a previous run, so it need not run on
+// every browser-enabled stream start. Throttle it per CDP endpoint.
+const REAP_THROTTLE_MS = 30_000;
+const lastReapAt = new Map();
+function reapStalePlaywrightMcpProcesses(cdpEndpoint) {
+    const reaped = [];
+    const spared = [];
+    if (process.platform === 'win32' || !cdpEndpoint)
+        return { reaped, spared };
+    const normalized = cdpEndpoint.replace(/\/+$/, '');
+    if (Date.now() - (lastReapAt.get(normalized) ?? 0) < REAP_THROTTLE_MS)
+        return { reaped, spared };
+    lastReapAt.set(normalized, Date.now());
+    const result = spawnSync('ps', ['-axo', 'pid=,ppid=,command='], { encoding: 'utf8' });
+    if (result.status !== 0)
+        return { reaped, spared };
+    const ppidByPid = new Map();
+    const candidates = [];
+    const lines = String(result.stdout || '').split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+    for (const line of lines) {
+        const m = line.match(/^(\d+)\s+(\d+)\s+(.*)$/);
+        if (!m)
+            continue;
+        const pid = Number(m[1]);
+        const ppid = Number(m[2]);
+        if (!Number.isFinite(pid) || !Number.isFinite(ppid))
+            continue;
+        ppidByPid.set(pid, ppid);
+        if (pid === process.pid)
+            continue;
+        const command = m[3] || '';
+        if (!_matchPlaywrightMcpProcessCommand(command, normalized))
+            continue;
+        candidates.push(pid);
+    }
+    const isOurDescendant = (pid) => {
+        let cur = pid;
+        for (let depth = 0; depth < 30 && cur != null && cur > 1; depth++) {
+            if (cur === process.pid)
+                return true;
+            cur = ppidByPid.get(cur);
+        }
+        return false;
+    };
+    for (const pid of candidates) {
+        if (isOurDescendant(pid)) {
+            spared.push(pid);
+            continue;
+        }
+        try {
+            process.kill(pid, 'SIGTERM');
+            reaped.push(pid);
+        }
+        catch {
+            // Already dead — no-op.
+        }
+    }
+    return { reaped, spared };
+}
+/**
+ * Decide which CDP endpoint the per-session playwright/mcp should attach to.
+ *
+ * When `PIKILOOP_BROWSER_CDP_URL` is set we return it UNCONDITIONALLY (mode
+ * `remote`) — without probing it for reachability. This is deliberate: the
+ * documented contract is that pikiloop never launches, probes, or kills a local
+ * Chrome in remote mode (e.g. inside a headless container that has no Chrome at
+ * all). Gating on a reachability ping would let a momentarily-unreachable
+ * sidecar fall through to the local-launch branch and silently spawn a browser
+ * — exactly the bug reported in #16. Handing `--cdp-endpoint <url>` to
+ * playwright/mcp instead surfaces an honest connection error on the first
+ * `browser_*` call if the sidecar is down.
+ *
+ * Without the override, fall back to probing the local managed Chrome via its
+ * DevToolsActivePort file (cross-process attach); `none` means leave Chrome
+ * unlaunched and let playwright/mcp cold-start one with `--user-data-dir`.
+ */
+export async function resolveBridgeBrowserEndpoint(profileDir = getManagedBrowserProfileDir(), remoteCdpUrl = getConfiguredRemoteCdpUrl()) {
+    if (remoteCdpUrl)
+        return { endpoint: remoteCdpUrl, mode: 'remote' };
+    const local = await resolveManagedBrowserCdpEndpoint(profileDir).catch(() => null);
+    return { endpoint: local, mode: local ? 'local-attach' : 'none' };
+}
+// ---------------------------------------------------------------------------
+// Bridge implementation
+// ---------------------------------------------------------------------------
+const ARTIFACT_MAX_BYTES = MCP_ARTIFACT_MAX_BYTES;
+const SEND_FILE_TIMEOUT_MS = MCP_TIMEOUTS.sendFile;
+const PHOTO_EXTS = new Set(['.jpg', '.jpeg', '.png', '.webp']);
+function isPhotoFile(filePath) {
+    return PHOTO_EXTS.has(path.extname(filePath).toLowerCase());
+}
+/** Check if realFile is inside any of the allowed root directories. */
+function isInsideAllowedRoot(realFile, allowedRoots) {
+    for (const root of allowedRoots) {
+        try {
+            const realRoot = fs.realpathSync(root);
+            const rel = path.relative(realRoot, realFile);
+            if (rel && !rel.startsWith('..') && !path.isAbsolute(rel))
+                return true;
+        }
+        catch { /* root doesn't exist, skip */ }
+    }
+    return false;
+}
+export function resolveSendFilePath(inputPath, workspacePath, stagedFiles = [], workdir) {
+    const requested = String(inputPath || '').trim();
+    if (!requested)
+        return { path: null, error: 'path is required' };
+    if (path.isAbsolute(requested))
+        return { path: requested };
+    const roots = {
+        workspace: path.resolve(workspacePath),
+        workdir: workdir ? path.resolve(workdir) : '',
+        tmp: path.resolve(os.tmpdir()),
+    };
+    const aliasPrefixes = [
+        { prefix: '@workspace/', root: roots.workspace },
+        { prefix: 'workspace:', root: roots.workspace },
+        { prefix: 'ws:', root: roots.workspace },
+        ...(roots.workdir ? [
+            { prefix: '@workdir/', root: roots.workdir },
+            { prefix: 'workdir:', root: roots.workdir },
+            { prefix: 'wd:', root: roots.workdir },
+        ] : []),
+        { prefix: '@tmp/', root: roots.tmp },
+        { prefix: 'tmp:', root: roots.tmp },
+    ];
+    for (const { prefix, root } of aliasPrefixes) {
+        if (!requested.startsWith(prefix))
+            continue;
+        const suffix = requested.slice(prefix.length).trim();
+        return { path: suffix ? path.resolve(root, suffix) : root };
+    }
+    const candidates = [
+        path.resolve(roots.workspace, requested),
+        ...(roots.workdir ? [path.resolve(roots.workdir, requested)] : []),
+    ];
+    for (const candidate of candidates) {
+        try {
+            fs.realpathSync(candidate);
+            return { path: candidate };
+        }
+        catch {
+            // Try next candidate.
+        }
+    }
+    if (!requested.includes('/') && !requested.includes(path.sep)) {
+        const basenameMatches = new Map();
+        const dedupedMatches = [];
+        const addMatch = (candidate) => {
+            const key = path.resolve(candidate);
+            if (basenameMatches.has(key))
+                return;
+            basenameMatches.set(key, key);
+            dedupedMatches.push(key);
+        };
+        try {
+            const tmpCandidate = path.join(roots.tmp, requested);
+            if (fs.existsSync(tmpCandidate))
+                addMatch(tmpCandidate);
+        }
+        catch { }
+        for (const relPath of stagedFiles) {
+            if (path.basename(relPath) !== requested)
+                continue;
+            addMatch(path.join(roots.workspace, relPath));
+        }
+        if (dedupedMatches.length === 1)
+            return { path: dedupedMatches[0] };
+        if (dedupedMatches.length > 1) {
+            return {
+                path: null,
+                error: `ambiguous file name "${requested}"; use @workspace/..., @workdir/..., or @tmp/...`,
+            };
+        }
+    }
+    return {
+        path: candidates[0] || null,
+        error: `file not found: ${requested}; try @workspace/..., @workdir/..., @tmp/..., or a unique filename`,
+    };
+}
+export async function startMcpBridge(opts) {
+    const { sessionDir, workspacePath, stagedFiles, sendFile, onInteraction } = opts;
+    let hadActivity = false;
+    const gui = resolveGuiIntegrationConfig();
+    for (const hint of buildGuiSetupHints(gui))
+        opts.onLog?.(hint);
+    // Lazy browser lifecycle: probe an already-running managed Chrome via
+    // <profileDir>/DevToolsActivePort and attach if reachable; otherwise leave
+    // Chrome unlaunched and let playwright/mcp launch it with `--user-data-dir`
+    // on the first browser_* tool call. Previously the bridge eagerly called
+    // `ensureManagedBrowser`, which forced a Chrome window to open at every
+    // stream start even when the agent never touched the browser.
+    let browserCdpEndpoint = null;
+    if (gui.browserEnabled) {
+        // Write the playwright/mcp config file (referenced by --config in
+        // getManagedBrowserMcpArgs) before the agent CLI spawns playwright/mcp.
+        ensurePlaywrightMcpConfigFile();
+        const { endpoint, mode } = await resolveBridgeBrowserEndpoint(gui.browserProfileDir);
+        browserCdpEndpoint = endpoint;
+        if (endpoint) {
+            opts.onLog?.(mode === 'remote'
+                ? `attaching to remote CDP endpoint ${endpoint} (PIKILOOP_BROWSER_CDP_URL); local Chrome launch disabled.`
+                : `attaching to existing managed browser at ${endpoint}.`);
+            // Clear stale playwright-mcp children still bound to this endpoint (one
+            // playwright-mcp per browser, per microsoft/playwright-mcp#1299). Safe for
+            // the remote sidecar too — it only ever SIGTERMs local playwright-mcp
+            // processes, never the Chrome itself.
+            const { reaped, spared } = reapStalePlaywrightMcpProcesses(endpoint);
+            if (reaped.length) {
+                opts.onLog?.(`reaped ${reaped.length} stale playwright-mcp process(es) attached to ${endpoint}: pid=${reaped.join(',')}${spared.length ? ` (spared in-tree: ${spared.join(',')})` : ''}`);
+            }
+        }
+        else {
+            opts.onLog?.('no managed browser running; playwright/mcp will launch one on first browser_* tool call.');
+        }
+    }
+    // Build allowed roots: workspace + workdir + /tmp
+    const allowedRoots = [workspacePath];
+    if (opts.workdir)
+        allowedRoots.push(opts.workdir);
+    allowedRoots.push('/tmp', os.tmpdir());
+    // ── HTTP callback server ──
+    // Started only when an IM-side callback is wired up, to serve:
+    //   - `im_send_file`  → /send-file
+    //   - `im_ask_user`   → /ask-user
+    //   - structured tool-activity logging from the in-process MCP server → /log
+    let callbackServer = null;
+    let port = 0;
+    const needsCallbackServer = !!sendFile || !!onInteraction;
+    if (needsCallbackServer) {
+        callbackServer = http.createServer((req, res) => {
+            const endpoint = req.url || '';
+            const known = endpoint === '/send-file' || endpoint === '/log' || endpoint === '/ask-user';
+            if (req.method !== 'POST' || !known) {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
+            // /ask-user blocks until the user replies; disable timeouts for it.
+            if (endpoint === '/ask-user') {
+                req.setTimeout(0);
+                res.setTimeout(0);
+            }
+            let body = '';
+            req.on('data', (chunk) => { body += chunk; });
+            // Timeout for receiving the request body
+            const bodyTimer = setTimeout(() => {
+                req.destroy(new Error('request body timeout'));
+            }, MCP_TIMEOUTS.requestBody);
+            req.on('end', async () => {
+                clearTimeout(bodyTimer);
+                try {
+                    if (endpoint === '/log') {
+                        const data = JSON.parse(body || '{}');
+                        const message = typeof data.message === 'string' ? data.message.trim() : '';
+                        if (message) {
+                            hadActivity = true;
+                            opts.onLog?.(message);
+                        }
+                        res.writeHead(200, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ ok: true }));
+                        return;
+                    }
+                    if (endpoint === '/ask-user') {
+                        if (!onInteraction) {
+                            res.writeHead(503, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ ok: false, error: 'ask-user is not available for this session' }));
+                            return;
+                        }
+                        const data = JSON.parse(body || '{}');
+                        const question = typeof data.question === 'string' ? data.question.trim() : '';
+                        if (!question) {
+                            res.writeHead(400, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ ok: false, error: 'question is required' }));
+                            return;
+                        }
+                        const header = typeof data.header === 'string' ? data.header.trim() : '';
+                        const hint = typeof data.hint === 'string' ? data.hint.trim() : '';
+                        const allowFreeform = data.allowFreeform == null ? true : !!data.allowFreeform;
+                        const rawOptions = Array.isArray(data.options) ? data.options : [];
+                        const interactionOptions = rawOptions
+                            .map((o) => {
+                            const label = typeof o?.label === 'string' ? o.label.trim() : '';
+                            const description = typeof o?.description === 'string' ? o.description.trim() : '';
+                            return label ? { label, description: description || null, value: label } : null;
+                        })
+                            .filter((o) => !!o);
+                        const questionId = 'ask-user';
+                        const interactionQuestion = {
+                            id: questionId,
+                            header: header || 'Question',
+                            prompt: question,
+                            options: interactionOptions.length ? interactionOptions : null,
+                            allowFreeform: interactionOptions.length ? allowFreeform : true,
+                        };
+                        const requestId = `ask-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+                        const interaction = {
+                            kind: 'user-input',
+                            id: requestId,
+                            title: header || 'Pikiloop needs your input',
+                            hint: hint || null,
+                            questions: [interactionQuestion],
+                            resolveWith: (answers) => {
+                                const values = answers[questionId] || [];
+                                const text = values.map(v => String(v ?? '').trim()).filter(Boolean).join(' ');
+                                return { answer: text };
+                            },
+                        };
+                        hadActivity = true;
+                        try {
+                            const response = await onInteraction(interaction);
+                            const answer = typeof response?.answer === 'string' ? response.answer : '';
+                            res.writeHead(200, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ ok: true, answer }));
+                        }
+                        catch (askErr) {
+                            res.writeHead(200, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ ok: false, error: askErr?.message || 'ask-user cancelled' }));
+                        }
+                        return;
+                    }
+                    // endpoint === '/send-file'
+                    if (!sendFile) {
+                        res.writeHead(503, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ ok: false, error: 'send-file is not available for this session' }));
+                        return;
+                    }
+                    const data = JSON.parse(body);
+                    const relPath = String(data.path || '').trim();
+                    if (!relPath) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ ok: false, error: 'path is required' }));
+                        return;
+                    }
+                    // Resolve and validate path
+                    const resolved = resolveSendFilePath(relPath, workspacePath, stagedFiles, opts.workdir);
+                    const absPath = resolved.path;
+                    let realFile;
+                    try {
+                        realFile = fs.realpathSync(String(absPath || ''));
+                    }
+                    catch {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ ok: false, error: resolved.error || `file not found: ${relPath}` }));
+                        return;
+                    }
+                    if (!isInsideAllowedRoot(realFile, allowedRoots)) {
+                        res.writeHead(403, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ ok: false, error: 'file must be inside the workspace, workdir, or /tmp' }));
+                        return;
+                    }
+                    // Size check
+                    const stat = fs.statSync(realFile);
+                    if (!stat.isFile()) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ ok: false, error: 'not a regular file' }));
+                        return;
+                    }
+                    if (stat.size > ARTIFACT_MAX_BYTES) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ ok: false, error: `file too large (${stat.size} bytes, max ${ARTIFACT_MAX_BYTES})` }));
+                        return;
+                    }
+                    // Auto-detect kind
+                    const kind = data.kind === 'photo' ? 'photo'
+                        : data.kind === 'document' ? 'document'
+                            : isPhotoFile(realFile) ? 'photo'
+                                : 'document';
+                    const caption = typeof data.caption === 'string' ? data.caption.trim().slice(0, 1024) || undefined : undefined;
+                    hadActivity = true;
+                    const result = await Promise.race([
+                        sendFile(realFile, { caption, kind }),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error(`sendFile timed out after ${SEND_FILE_TIMEOUT_MS / 1000}s`)), SEND_FILE_TIMEOUT_MS)),
+                    ]);
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(result));
+                }
+                catch (e) {
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: e?.message || 'internal error' }));
+                }
+            });
+        });
+        // Per-request body timers above guard against partial uploads.
+        callbackServer.headersTimeout = MCP_TIMEOUTS.serverHeaders;
+        // /ask-user can block indefinitely; drop the server-wide request timeout
+        // when that endpoint is wired up.
+        if (onInteraction)
+            callbackServer.requestTimeout = 0;
+        await new Promise((resolve, reject) => {
+            callbackServer.on('error', reject);
+            callbackServer.listen(0, '127.0.0.1', () => resolve());
+        });
+        port = callbackServer.address().port;
+    }
+    // ── Register MCP server with the agent ──
+    const supplementalServers = buildSupplementalMcpServers(gui, { cdpEndpoint: browserCdpEndpoint });
+    const servers = [...supplementalServers];
+    // Register the pikiloop stdio MCP server when any in-process tool needs the
+    // callback channel. `MCP_TOOLS_AVAILABLE` tells the server which tool
+    // families to advertise.
+    if (port && (sendFile || onInteraction)) {
+        const { command, args } = resolveMcpServerCommand();
+        const enabledTools = [];
+        if (sendFile)
+            enabledTools.push('workspace');
+        // Codex has native user-input via JSON-RPC; don't expose `im_ask_user`.
+        if (onInteraction && opts.agent !== 'codex')
+            enabledTools.push('ask-user');
+        const envVars = {
+            MCP_WORKSPACE_PATH: workspacePath,
+            MCP_WORKDIR: opts.workdir || '',
+            MCP_AGENT: opts.agent || '',
+            MCP_STAGED_FILES: JSON.stringify(stagedFiles),
+            MCP_CALLBACK_URL: `http://127.0.0.1:${port}`,
+            MCP_LOG_URL: `http://127.0.0.1:${port}/log`,
+            MCP_TOOLS_AVAILABLE: enabledTools.join(','),
+        };
+        servers.unshift({ name: 'pikiloop', command, args, env: envVars });
+    }
+    // Nothing to register — skip bridge entirely
+    if (!servers.length) {
+        if (callbackServer)
+            await new Promise(resolve => callbackServer.close(() => resolve()));
+        return null;
+    }
+    let configPath = '';
+    let extraEnv;
+    let mcpServers;
+    const codexRegisteredNames = [];
+    if (opts.agent === 'codex') {
+        // Codex: register MCP servers via `codex mcp add/remove`
+        // Include global + workspace extensions alongside built-in servers
+        const extServers = getGlobalExtensionsAsServers(opts.workdir);
+        const allServers = [...extServers, ...servers];
+        // Bearer tokens for HTTP MCP servers are injected into codex's process env
+        // via extraEnv — codex's `--bearer-token-env-var` only accepts an env name,
+        // never a literal token, so the value MUST land in the child env.
+        const codexBearerEnv = {};
+        // Sequential (codex serializes its own config writes) but async, so the
+        // per-server spawns don't block the event loop at stream start.
+        for (const server of allServers) {
+            const codexArgs = buildCodexMcpAddArgs(server, codexBearerEnv);
+            if (!codexArgs)
+                continue;
+            try {
+                await execFileAsync('codex', codexArgs, { timeout: MCP_TIMEOUTS.codexMcpAdd });
+                codexRegisteredNames.push(server.name);
+            }
+            catch {
+                try {
+                    await execFileAsync('codex', ['mcp', 'remove', server.name], { timeout: MCP_TIMEOUTS.codexMcpRemove });
+                }
+                catch { }
+                await execFileAsync('codex', codexArgs, { timeout: MCP_TIMEOUTS.codexMcpAdd });
+                codexRegisteredNames.push(server.name);
+            }
+        }
+        if (Object.keys(codexBearerEnv).length) {
+            extraEnv = { ...(extraEnv || {}), ...codexBearerEnv };
+        }
+    }
+    else if (opts.agent === 'gemini') {
+        // Gemini CLI 0.32+ loads MCP servers from settings.json rather than --mcp-config.
+        // Include global + workspace extensions alongside built-in servers
+        const extServers = getGlobalExtensionsAsServers(opts.workdir);
+        const allServers = [...extServers, ...servers];
+        configPath = path.join(sessionDir, 'gemini-system-settings.json');
+        const config = buildGeminiMcpConfig(allServers);
+        fs.mkdirSync(sessionDir, { recursive: true });
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+        extraEnv = { GEMINI_CLI_SYSTEM_SETTINGS_PATH: configPath };
+    }
+    else if (opts.agent === 'hermes') {
+        // Hermes consumes structured MCP server objects via ACP `session/new`,
+        // not a config file path. Resolve the merged server list and expose it
+        // on the bridge handle so the driver can translate to ACP's wire format.
+        mcpServers = mergeExtensionsForSession(servers, opts.workdir);
+    }
+    else {
+        // Claude: write MCP config JSON for --mcp-config
+        // Uses centralized merge: global extensions → .mcp.json files → built-in servers
+        configPath = path.join(sessionDir, 'mcp-config.json');
+        mcpServers = mergeExtensionsForSession(servers, opts.workdir);
+        fs.mkdirSync(sessionDir, { recursive: true });
+        fs.writeFileSync(configPath, JSON.stringify({ mcpServers }, null, 2));
+    }
+    return {
+        configPath,
+        extraEnv,
+        mcpServers,
+        hadActivity: () => hadActivity,
+        stop: async () => {
+            if (callbackServer)
+                await new Promise(resolve => callbackServer.close(() => resolve()));
+            for (const name of [...codexRegisteredNames].reverse()) {
+                try {
+                    await execFileAsync('codex', ['mcp', 'remove', name], { timeout: MCP_TIMEOUTS.codexMcpRemove });
+                }
+                catch { }
+            }
+            if (configPath) {
+                try {
+                    fs.rmSync(configPath, { force: true });
+                }
+                catch { }
+            }
+        },
+    };
+}