@stage-labs/metro 0.1.0-beta.27 → 0.1.0-beta.271

package/dist/cli.js

@@ -1,143 +1,93 @@
 #!/usr/bin/env node
-import { hostname } from 'node:os';
-import { claimCode, claimRuntime, mcpServers, NotSignedIn, whoisAuthorized, } from './api.js';
-import { askSecret } from './prompt.js';
-import { clearToken, credentialsPath, metroUrl, metroWebUrl, writeToken, } from './store.js';
-import { detach, lockedBy, probe, runningPid, stopAll, tail } from './control.js';
+import { whoisAuthorized } from './api.js';
+import { stopAll } from './control.js';
 import { tailEvents } from './tail.js';
-import { assertAgentId, daemonPlan, localUrl, readRunToken, runDaemon, runtimeDir, writeRunToken, } from './runtime.js';
-import { installPlugin, syncPluginServers } from './plugin.js';
+import { agentSession } from './agent.js';
+import { launchClaude } from './claude.js';
+import { memoryPaths, memoryRoutine } from './memory.js';
 import { update } from './update.js';
+import { serve } from './serve.js';
+import { service, serviceStopHint } from './service.js';
 import { currentVersion } from './version.js';
-const USAGE = `metro — the command line for your MCP connectors
+import { voiceSession } from './voice.js';
+const USAGE = `metro: run your agent on this machine
 
-  metro start <agent-id> [--detach]
-                  run that agent's stations on this machine
-  metro stop [agent-id]
-                  stop every metro daemon on this machine, however it was started
-  metro status <agent-id>
-                  is it running, and is it healthy
-  metro logs <agent-id> [-f]
-                  show the detached daemon's log
-  metro tail <agent-id>
+  metro serve [--port <n>] [--owner <organization id>]
+                  run the daemon: the agent, its channels and its connectors live in
+                  ~/.metro/agents here, and it is published through Tailscale Funnel at a
+                  permanent https://<machine>.<tailnet>.ts.net (Tailscale installed and
+                  signed in on this machine); the page at metro.box manages it through the
+                  link it prints; --owner names the organization whose members may sign
+                  in, needed on the first start only; Stop on the page parks the daemon and keeps the
+                  address, so Start works from the page too
+  metro service install [--port <n>] [--owner <organization id>] [--user metro]
+                  run metro serve as a service (systemd on Linux, launchd on macOS): it
+                  starts at boot and after a crash, so the page can stop, start and
+                  restart it with no shell; on Linux, root passes --user metro so Metro
+                  runs as its own user and Claude Code as the user agent;
+                  metro service uninstall and status as well
+  metro stop      stop metro on this machine, metro serve included
+  metro tail [agent-id]
                   follow this machine's inbound events, one JSON line each
-  metro login     authorize a connector collection with a code from the web UI
-  metro logout    forget this machine's sign-in
-  metro whoami    print the account and collection this machine may read
-  metro mcp       print the mcpServers block for the authorized collection
-  metro plugin    set up the Claude Code plugin (connector servers + /metro:login)
-  metro update    update to the newest published version
+  metro whoami    print the agent this machine runs
+  metro claude [args...]
+                  open Claude Code with the metro channel and the metro MCP server, its
+                  inference routed through the daemon's model gateway (the Model page);
+                  every argument is passed through the same
+  metro agent     run chat, calls and background workers in one Agent SDK conversation,
+                  when the Harness runner is Agent SDK, using the Model page's model;
+                  resume it after a restart; call audio runs independently
+  metro agent --prepare [cli|sdk]
+                  check the runner before selecting it; install the SDK runtime if needed,
+                  without starting a session or connecting to chat
+  metro memory [skill file]
+                  run the memory routine once: when Claude Code transcripts changed since
+                  the last run, Claude Code reads the memory skill (or the file given) and
+                  files them into its memory, with no metro tools and writes only inside
+                  the memory folder
+  metro voice --model <model>
+                  the agent's side of a voice call, which the daemon starts when a call
+                  comes in: Claude Code reads the call's words as stream-json on stdin and
+                  streams its replies on stdout, with the agent's memory, skills, plugin,
+                  connectors and metro tools (on /mcp/voice, so the chat session keeps its
+                  slot) but no metro channel; tool approvals come back on stdout
+  metro update    update to the newest published version (--check only reports)
   metro version   print this CLI's version
 
-Start Claude Code with all of them, without writing them to disk:
-
-  claude --mcp-config <(metro mcp)
-
-  METRO_URL          the metro to talk to (default https://mcp.metro.box)
-  METRO_UI_URL       where the web UI lives (default https://metro.box)
-  METRO_TOKEN        use this connector sign-in instead of the stored one
-  METRO_RUN_TOKEN    use this runtime authorization instead of the stored one
+  METRO_WEBHOOK_PORT the daemon's port (default 8420)
+  METRO_AGENTS_DIR   where the agents live (default ~/.metro/agents)
+  METRO_AGENT_KEY    the key metro tail presents, instead of the agent file's
   METRO_RUNTIME_DIR  run the daemon from this directory instead of the bundled one
 `;
-function hostLabel() {
-    const name = hostname().trim();
-    return name === '' ? 'unnamed machine' : name;
-}
-async function authorizeRuntime(agentId) {
-    process.stderr.write(`Authorize this machine at ${metroWebUrl()}/#/authorize/${agentId}\n`);
-    const code = (await askSecret('Paste the code (input is hidden): ')).trim();
-    if (code === '')
-        throw new Error('no code given');
-    const claimed = await claimRuntime(code, hostLabel());
-    writeRunToken(claimed.agent, claimed.token);
-    process.stderr.write(`Authorized as '${claimed.label}'.\n`);
-    return claimed.token;
-}
-async function start(argv) {
-    const agentId = assertAgentId(argv[0]);
-    if (runningPid(agentId) !== null || lockedBy() !== null)
-        throw new Error('a metro daemon is already running on this machine. ' +
-            'Stop it first: metro stop');
-    const dir = runtimeDir();
-    const token = readRunToken(agentId) ?? (await authorizeRuntime(agentId));
-    const detached = argv.includes('--detach');
-    const plan = daemonPlan({ agentId, token, dir });
-    if (!detached)
-        return runDaemon(agentId, plan);
-    const pid = detach({ agentId, ...plan });
-    process.stderr.write(`metro is running for ${agentId} (pid ${String(pid)})\n` +
-        `  logs:  metro logs ${agentId} -f\n` +
-        `  stop:  metro stop ${agentId}\n`);
-    return 0;
-}
-async function stopDaemon(argv) {
-    const agentId = argv[0] === undefined ? undefined : assertAgentId(argv[0]);
-    const stopped = await stopAll(agentId);
+async function stopDaemon() {
+    const stopped = await stopAll();
     if (stopped.length === 0) {
         process.stderr.write('no metro daemon is running on this machine\n');
         return 1;
     }
     for (const d of stopped)
         process.stderr.write(`Stopped metro (pid ${String(d.pid)}, via ${d.via})\n`);
+    const hint = serviceStopHint();
+    if (hint !== null)
+        process.stderr.write(`${hint}\n`);
     return 0;
 }
-async function status(argv) {
-    const agentId = assertAgentId(argv[0]);
-    const pid = runningPid(agentId);
-    if (pid === null) {
-        process.stdout.write(`${agentId}: not running\n`);
-        return 1;
-    }
-    const health = await probe(localUrl());
-    process.stdout.write(`${agentId}: running (pid ${String(pid)}) · ` +
-        (health === null
-            ? `not answering on ${localUrl()}\n`
-            : `healthy, up ${String(health.uptime)}s\n`));
-    return health === null ? 1 : 0;
-}
-function logs(argv) {
-    const agentId = assertAgentId(argv[0]);
-    return tail(agentId, argv.includes('-f') || argv.includes('--follow'));
-}
-async function login() {
-    process.stderr.write(`Choose a connector collection at ${metroWebUrl()}/#/authorize\n`);
-    const { token, email, collection } = await claimCode(await askSecret('Paste the code here (input is hidden): '));
-    writeToken(token);
-    process.stderr.write(`Authorized '${collection}' for ${email}. Stored in ${credentialsPath()}\n`);
-    if (syncPluginServers())
-        process.stderr.write('Claude Code plugin refreshed — new sessions have the connectors; ' +
-            'run /reload-plugins in any session already open.\n');
-}
-async function whoami() {
-    const { email, collection } = await whoisAuthorized();
-    process.stdout.write(`${email} · collection '${collection}' on ${metroUrl()}\n`);
-}
 const HELP = new Set([undefined, 'help', '--help', '-h']);
 const COMMANDS = {
-    login: async () => {
-        await login();
-        return 0;
-    },
-    logout: async () => {
-        clearToken();
-        process.stderr.write('Signed out.\n');
-        return Promise.resolve(0);
-    },
     whoami: async () => {
-        await whoami();
+        const { agent, where } = await whoisAuthorized();
+        process.stdout.write(`agent ${agent} on ${where}\n`);
         return 0;
     },
-    start: () => start(process.argv.slice(3)),
-    stop: () => stopDaemon(process.argv.slice(3)),
-    status: () => status(process.argv.slice(3)),
-    logs: () => logs(process.argv.slice(3)),
+    serve: () => serve(process.argv.slice(3)),
+    service: () => service(process.argv.slice(3)),
+    stop: stopDaemon,
     tail: () => tailEvents(process.argv.slice(3)),
-    mcp: async () => {
-        process.stdout.write(`${await mcpServers()}\n`);
-        return 0;
-    },
-    plugin: installPlugin,
-    update,
+    claude: () => launchClaude(process.argv.slice(3)),
+    agent: () => agentSession(process.argv.slice(3)),
+    memory: () => memoryRoutine(memoryPaths(process.env, process.argv[3])),
+    voice: () => voiceSession(process.argv.slice(3)),
+    update: () => update(process.argv.slice(3)),
     version: async () => {
         process.stdout.write(`${currentVersion()}\n`);
         return Promise.resolve(0);
@@ -153,6 +103,6 @@ async function run(command) {
 const code = await run(process.argv[2]).catch((err) => {
     const message = err instanceof Error ? err.message : String(err);
     process.stderr.write(`metro: ${message}\n`);
-    return err instanceof NotSignedIn ? 2 : 1;
+    return 1;
 });
 process.exit(code);

package/dist/control.js

@@ -1,23 +1,13 @@
-import { execFileSync, spawn } from 'node:child_process';
-import { existsSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { readFileSync, rmSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-const STATE = () => join(homedir(), '.metro');
-const pidPath = (agentId) => join(STATE(), `run-${agentId}.pid`);
-export const logPath = (agentId) => join(STATE(), 'logs', `${agentId}.log`);
-function ensureStateDirs() {
-    mkdirSync(STATE(), { recursive: true, mode: 0o700 });
-    mkdirSync(join(STATE(), 'logs'), { recursive: true, mode: 0o700 });
-}
-function readPid(agentId) {
-    try {
-        const pid = Number(readFileSync(pidPath(agentId), 'utf8').trim());
-        return Number.isInteger(pid) && pid > 0 ? pid : null;
-    }
-    catch {
-        return null;
-    }
+export function serveStateDir() {
+    const xdg = process.env.XDG_CACHE_HOME?.trim();
+    const base = xdg === undefined || xdg === '' ? join(homedir(), '.cache') : xdg;
+    return join(base, 'metro', 'serve');
 }
+const serveLockPath = () => join(serveStateDir(), '.tail-lock');
 function isAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -27,37 +17,6 @@ function isAlive(pid) {
         return false;
     }
 }
-export function runningPid(agentId) {
-    const pid = readPid(agentId);
-    if (pid === null)
-        return null;
-    if (isAlive(pid))
-        return pid;
-    rmSync(pidPath(agentId), { force: true });
-    return null;
-}
-function writePid(agentId, pid) {
-    writeFileSync(pidPath(agentId), String(pid));
-}
-function clearPid(agentId) {
-    rmSync(pidPath(agentId), { force: true });
-}
-export function detach(opts) {
-    ensureStateDirs();
-    const out = openSync(logPath(opts.agentId), 'a');
-    const child = spawn(opts.command, opts.args, {
-        cwd: opts.cwd,
-        env: opts.env,
-        detached: true,
-        stdio: ['ignore', out, out],
-    });
-    child.unref();
-    const pid = child.pid ?? 0;
-    if (pid === 0)
-        throw new Error('could not start the metro daemon');
-    writePid(opts.agentId, pid);
-    return pid;
-}
 async function stopPid(pid, waitMs) {
     process.kill(pid, 'SIGTERM');
     const until = Date.now() + waitMs;
@@ -83,10 +42,10 @@ function commandOf(pid) {
     }
 }
 const looksLikeMetro = (command) => command.includes('server.ts') || command.includes('metro');
-export function lockedBy() {
+function holderOf(lockFile) {
     let pid;
     try {
-        pid = Number(readFileSync(lockPath(), 'utf8').trim());
+        pid = Number(readFileSync(lockFile, 'utf8').trim());
     }
     catch {
         return null;
@@ -95,64 +54,21 @@ export function lockedBy() {
         return null;
     return looksLikeMetro(commandOf(pid)) ? pid : null;
 }
-function trackedAgents(agentId) {
-    const tracked = new Set();
-    if (agentId !== undefined)
-        tracked.add(agentId);
-    try {
-        for (const name of readdirSync(STATE())) {
-            const found = /^run-(.+)\.pid$/.exec(name);
-            if (found?.[1] !== undefined)
-                tracked.add(found[1]);
-        }
-    }
-    catch {
-        return tracked;
-    }
-    return tracked;
-}
-export async function stopAll(agentId, waitMs = 10_000) {
+export const lockedBy = () => holderOf(lockPath());
+export const serveLockedBy = () => holderOf(serveLockPath());
+export async function stopAll(waitMs = 10_000) {
     const stopped = [];
-    const seen = new Set();
-    for (const id of trackedAgents(agentId)) {
-        const pid = runningPid(id);
-        if (pid === null || seen.has(pid))
-            continue;
-        seen.add(pid);
-        await stopPid(pid, waitMs);
-        clearPid(id);
-        stopped.push({ pid, via: id });
-    }
     const holder = lockedBy();
-    if (holder !== null && !seen.has(holder)) {
+    if (holder !== null) {
         await stopPid(holder, waitMs);
         rmSync(lockPath(), { force: true });
         stopped.push({ pid: holder, via: 'the machine lock' });
     }
-    return stopped;
-}
-export function tail(agentId, follow) {
-    const path = logPath(agentId);
-    if (!existsSync(path))
-        throw new Error(`no log for ${agentId} yet — it is only written when started with --detach`);
-    const args = follow ? ['-n', '200', '-f', path] : ['-n', '200', path];
-    const child = spawn('tail', args, { stdio: ['ignore', 'inherit', 'inherit'] });
-    return new Promise((resolve) => {
-        child.on('exit', (code) => {
-            resolve(code ?? 0);
-        });
-    });
-}
-export async function probe(url) {
-    try {
-        const res = await fetch(`${url}/health`, {
-            signal: AbortSignal.timeout(3_000),
-        });
-        if (!res.ok)
-            return null;
-        return (await res.json());
-    }
-    catch {
-        return null;
+    const served = serveLockedBy();
+    if (served !== null && served !== holder) {
+        await stopPid(served, waitMs);
+        rmSync(serveLockPath(), { force: true });
+        stopped.push({ pid: served, via: 'metro serve' });
     }
+    return stopped;
 }

package/dist/hold.js

@@ -0,0 +1,210 @@
+import { spawn } from 'node:child_process';
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+const FUNNEL_RETRY_MS = 2_000;
+const FUNNEL_EXIT_WAIT_MS = 5_000;
+const LISTEN_ATTEMPTS = 10;
+const LISTEN_RETRY_MS = 500;
+const STOPPED = 503;
+export const STOPPED_MESSAGE = 'metro is stopped on this machine. Start it from the Server page on metro.box, or run metro serve.';
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+function corsHeaders(req) {
+    return {
+        'access-control-allow-origin': req.headers.origin ?? '*',
+        'access-control-allow-methods': 'GET, POST, PUT, DELETE, OPTIONS',
+        'access-control-allow-headers': 'Authorization, Content-Type',
+        'access-control-allow-private-network': 'true',
+        'access-control-max-age': '86400',
+        vary: 'Origin',
+    };
+}
+function sendJson(req, res, status, body) {
+    res.writeHead(status, {
+        'content-type': 'application/json',
+        'cache-control': 'no-store',
+        ...corsHeaders(req),
+    });
+    res.end(JSON.stringify(body));
+}
+function holdRequest(req, res, info, onStart) {
+    const path = (req.url ?? '').split('?')[0] ?? '';
+    if (req.method === 'OPTIONS') {
+        res.writeHead(204, corsHeaders(req)).end();
+        return;
+    }
+    if (path === '/api/mode' && req.method === 'GET') {
+        sendJson(req, res, 200, {
+            mode: 'local',
+            owner: info.owner,
+            version: info.version,
+            stopped: true,
+        });
+        return;
+    }
+    if (path === '/api/start') {
+        if (req.method !== 'POST') {
+            sendJson(req, res, 405, { error: 'method not allowed' });
+            return;
+        }
+        sendJson(req, res, 200, { starting: true });
+        onStart();
+        return;
+    }
+    if (path === '/health' || path === '/healthz') {
+        sendJson(req, res, STOPPED, { status: 'stopped', version: info.version });
+        return;
+    }
+    sendJson(req, res, STOPPED, { error: STOPPED_MESSAGE, stopped: true });
+}
+export const holdServer = (info, onStart) => createServer((req, res) => {
+    holdRequest(req, res, info, onStart);
+});
+const lastLine = (chunk) => String(chunk).trim().split('\n').at(-1) ?? '';
+class HeldFunnel {
+    bin;
+    port;
+    log;
+    child = null;
+    closed = false;
+    timer = null;
+    exits = 0;
+    constructor(bin, port, log) {
+        this.bin = bin;
+        this.port = port;
+        this.log = log;
+    }
+    start() {
+        if (this.closed)
+            return;
+        const child = spawn(this.bin, ['funnel', String(this.port)], { stdio: ['ignore', 'pipe', 'pipe'] });
+        this.child = child;
+        let last = '';
+        const read = (chunk) => {
+            const line = lastLine(chunk);
+            if (line !== '')
+                last = line;
+        };
+        child.stdout?.on('data', read);
+        child.stderr?.on('data', read);
+        child.on('error', (err) => {
+            this.child = null;
+            this.closed = true;
+            this.log(`funnel could not start (${err.message}); the loopback address is still held`);
+        });
+        child.on('exit', () => {
+            this.child = null;
+            if (this.closed)
+                return;
+            this.exits += 1;
+            if (this.exits > 1)
+                this.log(`funnel exited (${last}); retrying in ${String(FUNNEL_RETRY_MS / 1000)}s`);
+            this.timer = setTimeout(() => {
+                this.start();
+            }, FUNNEL_RETRY_MS);
+        });
+    }
+    async stop() {
+        this.closed = true;
+        if (this.timer !== null)
+            clearTimeout(this.timer);
+        const child = this.child;
+        this.child = null;
+        if (child === null)
+            return;
+        if (child.exitCode !== null || child.signalCode !== null)
+            return;
+        await new Promise((resolve) => {
+            const kill = setTimeout(() => {
+                child.kill('SIGKILL');
+            }, FUNNEL_EXIT_WAIT_MS);
+            child.once('exit', () => {
+                clearTimeout(kill);
+                resolve();
+            });
+            child.kill('SIGINT');
+        });
+    }
+}
+async function listen(server, info) {
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            await new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(info.port, info.host, () => {
+                    server.off('error', reject);
+                    resolve();
+                });
+            });
+            return;
+        }
+        catch (err) {
+            if (attempt >= LISTEN_ATTEMPTS)
+                throw err;
+            await wait(LISTEN_RETRY_MS);
+        }
+    }
+}
+const CLOSE_WAIT_MS = 2_000;
+const close = (server) => new Promise((resolve) => {
+    const timer = setTimeout(resolve, CLOSE_WAIT_MS);
+    server.close(() => {
+        clearTimeout(timer);
+        resolve();
+    });
+    server.closeAllConnections();
+});
+function releaseLock(lockFile) {
+    try {
+        if (readFileSync(lockFile, 'utf8').trim() === String(process.pid))
+            rmSync(lockFile, { force: true });
+    }
+    catch {
+        return;
+    }
+}
+function armFunnel(info, log, ending) {
+    if (info.funnel === null || ending !== null)
+        return null;
+    const funnel = new HeldFunnel(info.funnel, info.port, log);
+    funnel.start();
+    return funnel;
+}
+export const holdBanner = (info) => `metro is stopped. Holding http://${info.host}:${String(info.port)}${info.funnel === null ? '' : ' and the Funnel address'} ` +
+    'until Start on the Server page; Ctrl-C or metro stop ends metro serve';
+export async function holdUntilStart(info, deps = {}) {
+    const signals = deps.signals ?? process;
+    const log = deps.log ??
+        ((line) => {
+            process.stderr.write(`${line}\n`);
+        });
+    let finish = () => undefined;
+    let ending = null;
+    const ended = new Promise((resolve) => {
+        finish = (end) => {
+            ending ??= end;
+            resolve(end);
+        };
+    });
+    const server = holdServer(info, () => {
+        finish('start');
+    });
+    const onSignal = () => {
+        finish('exit');
+    };
+    signals.on('SIGINT', onSignal);
+    signals.on('SIGTERM', onSignal);
+    if (info.lockFile !== null)
+        writeFileSync(info.lockFile, String(process.pid));
+    await listen(server, info);
+    const funnel = armFunnel(info, log, ending);
+    if (ending === null)
+        log(holdBanner(info));
+    const end = await ended;
+    signals.off('SIGINT', onSignal);
+    signals.off('SIGTERM', onSignal);
+    await funnel?.stop();
+    await close(server);
+    if (info.lockFile !== null)
+        releaseLock(info.lockFile);
+    return end;
+}

package/dist/local.js

@@ -0,0 +1,43 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { localUrl } from './runtime.js';
+const PROBE_MS = 3_000;
+export function agentsDir() {
+    const explicit = process.env.METRO_AGENTS_DIR?.trim();
+    return explicit !== undefined && explicit !== '' ? explicit : join(homedir(), '.metro', 'agents');
+}
+function agentFile(dir) {
+    try {
+        return JSON.parse(readFileSync(join(dir, 'agent.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function localAgent(dir = agentsDir()) {
+    const file = agentFile(dir);
+    return typeof file?.id === 'string' && typeof file.key === 'string' ? { id: file.id, key: file.key } : null;
+}
+export function localStations(dir = agentsDir()) {
+    const stations = agentFile(dir)?.stations;
+    if (!Array.isArray(stations))
+        return [];
+    const out = new Set();
+    for (const s of stations) {
+        const station = s.station;
+        if (typeof station === 'string')
+            out.add(station);
+    }
+    return [...out].sort();
+}
+export async function localDaemonUp(base = localUrl()) {
+    try {
+        const res = await fetch(`${base}/api/mode`, { signal: AbortSignal.timeout(PROBE_MS) });
+        const body = (await res.json());
+        return res.ok && body.mode === 'local';
+    }
+    catch {
+        return false;
+    }
+}

package/dist/mcp-config.js

@@ -0,0 +1,27 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+const METRO_SERVER = 'metro';
+const CHAT_PATH = '/mcp';
+export const VOICE_MCP_PATH = '/mcp/voice';
+export function metroMcpConfig(agentKey, port, path = CHAT_PATH) {
+    const servers = {
+        [METRO_SERVER]: {
+            type: 'http',
+            url: `http://127.0.0.1:${String(port)}${path}`,
+            headers: { Authorization: `Bearer ${agentKey}` },
+        },
+    };
+    return `${JSON.stringify({ mcpServers: servers }, null, 2)}\n`;
+}
+export function writeMcpConfig(agentKey, port, base = tmpdir(), mcpPath = CHAT_PATH) {
+    const dir = mkdtempSync(join(base, 'metro-claude-'));
+    const path = join(dir, 'mcp.json');
+    writeFileSync(path, metroMcpConfig(agentKey, port, mcpPath), { mode: 0o600 });
+    return {
+        path,
+        cleanup: () => {
+            rmSync(dir, { recursive: true, force: true });
+        },
+    };
+}