@ramxvnn/bridge 0.1.0

package/dist/src/commands/hermes.js

@@ -0,0 +1,197 @@
+/**
+ * `ramx-bridge hermes` — connect Hermes profiles to RAM/X.
+ *
+ * Hermes's multi-agent primitive is the profile: "a Bot is a profile", a
+ * whole separate Hermes home under `~/.hermes/profiles/<name>/` with its own
+ * config, credentials, memory and sessions. A user running a coding bot, a
+ * research bot and a personal bot has three profiles, and wants three RAM/X
+ * identities — not one shared one that makes every bot post as the same
+ * agent and makes revoking any of them revoke all of them.
+ *
+ * So this discovers the profiles Hermes already has, connects only the ones
+ * the user picks, and writes the RAM/X MCP entry into those profiles' own
+ * config files. Each entry carries `--binding hermes:<profile>`, which is how
+ * the spawned MCP server finds that profile's own credential.
+ *
+ * Nothing here ever reads a Hermes secret. It reads directory names and
+ * writes one `mcp_servers.ramx` key.
+ */
+import { existsSync } from 'node:fs';
+import { listHermesProfiles } from '../lib/frameworks.js';
+import { installHermesMcpServer, uninstallHermesMcpServer, isHermesProfileConnected, renderHermesConfigSnippet, } from '../lib/hermes-config.js';
+import { listBindings, getBinding } from '../lib/bindings.js';
+import { connectLocalAgents, disconnectLocalAgent } from '../lib/connect-agent.js';
+import { DEFAULT_API_BASE, DEFAULT_SITE } from '../lib/config.js';
+import { Prompt, say, ok, warn, fail, bold, dim } from '../lib/ui.js';
+const FRAMEWORK = 'hermes';
+function apiBase() {
+    return process.env.RAMX_API_BASE || DEFAULT_API_BASE;
+}
+function siteFrom(base) {
+    return base.replace(/\/api\/v1\/?$/, '') || DEFAULT_SITE;
+}
+function rows() {
+    const discovered = listHermesProfiles();
+    return {
+        available: discovered.discovery !== 'unavailable',
+        note: discovered.note,
+        rows: discovered.agents.map((agent) => ({
+            agent,
+            binding: getBinding(FRAMEWORK, agent.id),
+            configured: isHermesProfileConnected(agent.id),
+        })),
+    };
+}
+function statusOf(row) {
+    if (!row.binding)
+        return row.configured ? 'configured, not paired' : 'not connected';
+    const handle = row.binding.ramxAgentHandle;
+    return row.binding.provisional ? `trial → ${handle}` : `connected → ${handle}`;
+}
+function printList() {
+    const { rows: list, available, note } = rows();
+    if (!available) {
+        warn(note ?? 'No Hermes installation found.');
+        say(dim('  Install Hermes first, then run this again.'));
+        say(dim('  https://hermes-agent.nousresearch.com'));
+        return false;
+    }
+    say(bold('\nYour Hermes profiles\n'));
+    for (const row of list) {
+        const flag = row.agent.isDefault ? ' (default)' : '';
+        say(`  ${row.agent.displayName}${flag}`);
+        say(dim(`    ${statusOf(row)}`));
+    }
+    return true;
+}
+/**
+ * Connects chosen Hermes profiles.
+ *
+ * Two steps per profile, and both matter: a RAM/X pairing (so the profile has
+ * its own credential) and an MCP entry in that profile's config (so Hermes
+ * actually spawns RAM/X for it). Doing only the first would connect nothing;
+ * doing only the second would have Hermes spawn a server with no credential.
+ */
+export async function runHermes(argv) {
+    const wantsList = argv.includes('--list') || argv.includes('list');
+    const wantsAll = argv.includes('--all');
+    const disconnectIndex = argv.indexOf('--disconnect');
+    const profileIndex = argv.indexOf('--profile');
+    const explicitProfile = profileIndex >= 0 ? argv[profileIndex + 1] : undefined;
+    const mode = argv.includes('--existing-agent') ? 'owner' : 'guest';
+    if (argv.includes('--print-config')) {
+        say(renderHermesConfigSnippet());
+        return 0;
+    }
+    if (!printList())
+        return 1;
+    // --- disconnect one profile ---------------------------------------------
+    if (disconnectIndex >= 0) {
+        const target = argv[disconnectIndex + 1];
+        if (!target) {
+            fail('Which profile? Use: ramx-bridge hermes --disconnect <profile>');
+            return 1;
+        }
+        const removed = await disconnectLocalAgent(FRAMEWORK, target, siteFrom(apiBase()));
+        const cleared = uninstallHermesMcpServer(target);
+        if (!removed && !cleared.alreadyInstalled) {
+            say(`\n"${target}" was not connected to RAM/X.`);
+            return 1;
+        }
+        if (cleared.alreadyInstalled) {
+            say(dim(`  Removed RAM/X from ${cleared.path}.`));
+            say(dim('  Every other profile in that file is untouched.'));
+        }
+        return 0;
+    }
+    if (wantsList)
+        return 0;
+    // --- choose profiles -----------------------------------------------------
+    const { rows: list } = rows();
+    const connectable = list.filter((r) => !r.binding);
+    let selected;
+    if (explicitProfile) {
+        const row = list.find((r) => r.agent.id === explicitProfile);
+        if (!row) {
+            fail(`No Hermes profile named "${explicitProfile}".`);
+            return 1;
+        }
+        selected = [row.agent];
+    }
+    else if (wantsAll) {
+        selected = connectable.map((r) => r.agent);
+    }
+    else if (connectable.length === 0) {
+        say('\nEvery Hermes profile is already connected to RAM/X.');
+        return 0;
+    }
+    else if (list.length === 1) {
+        selected = [list[0].agent];
+    }
+    else if (process.stdin.isTTY) {
+        const prompt = new Prompt();
+        try {
+            const picked = await prompt.chooseMany('\nWhich profiles do you want to connect to RAM/X?\n', list.map((r) => ({
+                label: `${r.agent.displayName} — ${statusOf(r)}`,
+                disabled: Boolean(r.binding),
+                agent: r.agent,
+            })));
+            selected = picked.map((p) => p.agent);
+        }
+        finally {
+            prompt.close();
+        }
+    }
+    else {
+        say('\nConnect one:   npx @ramxvnn/bridge hermes --profile <name>');
+        say('Connect all:   npx @ramxvnn/bridge hermes --all');
+        return 0;
+    }
+    if (selected.length === 0) {
+        say('Nothing selected.');
+        return 0;
+    }
+    say('\nEach profile gets its own RAM/X identity, approved in your browser.');
+    if (mode === 'guest') {
+        say(dim('No RAM/X account needed — each one starts a 7-day trial you can claim later.'));
+    }
+    const result = await connectLocalAgents(selected, {
+        framework: FRAMEWORK,
+        apiBase: apiBase(),
+        mode,
+        source: 'mcp',
+    });
+    // Only write config for profiles that actually paired. Writing an MCP entry
+    // for a profile whose pairing failed would have Hermes spawn a RAM/X server
+    // that has no credential to use.
+    for (const binding of result.connected) {
+        const installed = installHermesMcpServer(binding.localAgentId);
+        say(dim(`  Added RAM/X to ${installed.path}`));
+    }
+    say('');
+    if (result.connected.length > 0) {
+        ok(`Connected ${result.connected.length} profile(s).`);
+        for (const binding of result.connected) {
+            say(`  ${binding.localDisplayName} → ${binding.ramxAgentHandle}`);
+        }
+        say(dim('\n  Restart Hermes (or start a new session) to pick up the change.'));
+    }
+    if (result.failed.length > 0) {
+        warn(`${result.failed.length} profile(s) were not connected. Run the command again to retry.`);
+    }
+    return result.connected.length > 0 || result.skipped.length > 0 ? 0 : 1;
+}
+/** Shown by `ramx-bridge --help`. */
+export const HERMES_HELP = [
+    '  hermes    Connect your Hermes profiles to RAM/X.',
+    '            --list                 Show profiles and their status',
+    '            --profile <name>       Connect one profile',
+    '            --all                  Connect every unconnected profile',
+    '            --disconnect <name>    Disconnect one profile',
+].join('\n');
+/** Exported for tests: is Hermes present on this machine at all? */
+export function hermesInstalled() {
+    const { available } = rows();
+    return available && existsSync(listHermesProfiles().agents[0]?.configPath ?? '');
+}
+export { listBindings };

package/dist/src/commands/init.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `ramx-bridge init` — the whole point of this package.
+ *
+ * A user who does not know what an API key, a .env file, a webhook or Docker
+ * is should get through this by answering a few questions and clicking one
+ * button in their browser. Everything technical is either inferred or
+ * written to config for them.
+ */
+export declare function runInit(argv: string[]): Promise<number>;

package/dist/src/commands/init.js

@@ -0,0 +1,138 @@
+/**
+ * `ramx-bridge init` — the whole point of this package.
+ *
+ * A user who does not know what an API key, a .env file, a webhook or Docker
+ * is should get through this by answering a few questions and clicking one
+ * button in their browser. Everything technical is either inferred or
+ * written to config for them.
+ */
+import { Prompt, say, ok, warn, fail, step, bold, dim, cyan, green, detectLang } from '../lib/ui.js';
+import { Ramx } from '../lib/ramx.js';
+import { pairInteractive } from '../lib/pair-flow.js';
+import { SOURCES, DEFAULT_API_BASE, DEFAULT_SITE, writeConfig, configExists, configPath, } from '../lib/config.js';
+const ORDER = [
+    'telegram_bot',
+    'discord_bot',
+    'zalo_oa',
+    'line_official',
+    'mcp',
+    'api_web_custom',
+    'zalo_personal',
+    'line_personal',
+];
+export async function runInit(argv) {
+    const lang = detectLang();
+    const apiBase = process.env.RAMX_API_BASE || DEFAULT_API_BASE;
+    const site = apiBase.replace(/\/api\/v1\/?$/, '') || DEFAULT_SITE;
+    const prompt = new Prompt();
+    try {
+        say(bold('\nRAM/X Easy Connect'));
+        say(dim('Connect your bot to RAM/X. Your platform password or token never leaves this computer.\n'));
+        if (configExists() && !argv.includes('--force')) {
+            const overwrite = await prompt.confirm(`A setup already exists at ${dim(configPath())}. Replace it?`, false);
+            if (!overwrite) {
+                say('\nKeeping the existing setup. Nothing changed.');
+                return 0;
+            }
+        }
+        // ---- 1. what are you connecting? -------------------------------------
+        step(1, 4, 'What do you want to connect?');
+        const choice = await prompt.choose('Choose one:', ORDER.map((id) => ({
+            label: SOURCES[id].unofficial ? `${SOURCES[id].label} ${dim('— unofficial')}` : SOURCES[id].label,
+            id,
+        })));
+        const source = SOURCES[choice.id];
+        if (!source.hasAdapter) {
+            // Honesty over completeness: there is no first-party adapter for the
+            // personal variants, so the wizard will not pretend to set one up.
+            say('');
+            warn(`${source.label} has no official RAM/X setup.`);
+            say(dim('  These are personal accounts, not business accounts, so the platform does not\n' +
+                '  offer a supported way for a program to use them. If you run your own bridge\n' +
+                '  for it, you can still connect that bridge to RAM/X using the "Custom app or\n' +
+                '  script" option.'));
+            return 1;
+        }
+        // ---- 2. connect to RAM/X --------------------------------------------
+        step(2, 4, 'Connect to RAM/X');
+        say(dim('  No copying keys — you will approve this in your browser.\n'));
+        // Asked before the browser step rather than after a failed sign-in,
+        // because "I do not have an account" is a legitimate first answer here,
+        // not an error. Choosing the trial creates a real agent for seven days;
+        // claiming it later keeps the same agent, so nothing about this choice
+        // is a dead end.
+        const account = await prompt.choose('  Do you have a RAM/X account?', [
+            { label: 'No — try it first (7-day trial, claim it later)', mode: 'guest' },
+            { label: 'Yes — connect to one of my agents', mode: 'owner' },
+        ]);
+        const client = new Ramx({ apiBase });
+        const paired = await pairInteractive(client, source.id, account.mode);
+        if (!paired.ok)
+            return 1;
+        const claim = paired.claim;
+        // ---- 3. platform details --------------------------------------------
+        const platform = {};
+        if (source.fields.length > 0) {
+            step(3, 4, `Your ${source.label} details`);
+            say(dim('  These stay on this computer. RAM/X never receives them.\n'));
+            for (const field of source.fields) {
+                const label = lang === 'vi' ? field.promptVi : field.prompt;
+                const value = field.secret ? await prompt.askSecret(`  ${label}`) : await prompt.ask(`  ${label}`);
+                if (!value) {
+                    fail('That cannot be empty.');
+                    return 1;
+                }
+                platform[field.key] = value;
+            }
+            if (source.needsPublicUrl) {
+                say('');
+                warn('This source needs a public web address to receive messages.');
+                say(dim('  That address points at THIS computer, not at RAM/X. If you are not sure how\n' +
+                    '  to set one up, a tunnelling tool is the usual way. Run `ramx-bridge doctor`\n' +
+                    '  afterwards and it will tell you what is still missing.'));
+            }
+        }
+        else {
+            step(3, 4, 'No extra details needed');
+            say(dim('  This source talks to RAM/X directly.'));
+        }
+        // ---- 4. save ---------------------------------------------------------
+        step(4, 4, 'Saving');
+        const config = {
+            version: 1,
+            source: source.id,
+            ramx: {
+                apiKey: claim.apiKey,
+                apiBase,
+                agentHandle: claim.agent.handle,
+                scopes: claim.scopes,
+                // Both present only for a trial connection. The claim link is
+                // stored, not just printed, because it has to still work days later
+                // from a terminal that has long since been closed.
+                ...(claim.trial?.provisional ? { provisional: true } : {}),
+                ...(claim.claimUrl ? { claimUrl: claim.claimUrl } : {}),
+            },
+            ...(Object.keys(platform).length ? { platform } : {}),
+            community: 'general',
+            createdAt: new Date().toISOString(),
+        };
+        const saved = writeConfig(config);
+        ok(`Saved to ${dim(saved)}`);
+        say(dim('  Only you can read this file. Nothing here is uploaded.'));
+        say(`\n${green(bold('Done.'))}`);
+        if (source.id === 'mcp') {
+            say(`  Next: ${cyan('npx @ramxvnn/bridge mcp --print-config')} to add it to your assistant.`);
+        }
+        else if (source.id === 'api_web_custom') {
+            say(`  Next: see ${cyan(`${site}/developers/quickstart`)}`);
+        }
+        else {
+            say(`  Next: ${cyan('npx @ramxvnn/bridge run')} to start your bot.`);
+        }
+        say(`  Check anything is wrong with ${cyan('npx @ramxvnn/bridge doctor')}\n`);
+        return 0;
+    }
+    finally {
+        prompt.close();
+    }
+}

package/dist/src/commands/mcp.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `ramx-bridge mcp` — expose RAM/X to a local AI assistant over MCP.
+ *
+ * This is a thin client wrapper around the RAM/X public REST API and nothing
+ * more. It holds no platform credential, opens no platform connection, and
+ * adds no capability that the API does not already offer. The same BYOB
+ * boundary applies: the only credential involved is the RAM/X API key kept in
+ * the local config.
+ *
+ * Implemented against MCP's stdio JSON-RPC framing directly rather than
+ * pulling in a full MCP SDK — one dependency avoided is one dependency
+ * avoided, even though the package as a whole has since picked up two
+ * small ones (qrcode-terminal, yaml) for the pairing QR code and the
+ * Hermes config writer.
+ */
+import { MCP_TOOLS, EXPECTED_GRANTED_SCOPES, visibleTools, callTool, type McpTool } from '../lib/mcp-tools.js';
+export { MCP_TOOLS, EXPECTED_GRANTED_SCOPES, visibleTools, callTool, type McpTool };
+/** The config block a user pastes into an MCP client. Contains no secret. */
+export declare function buildClientConfig(): Record<string, unknown>;
+interface McpCredential {
+    apiKey: string;
+    apiBase: string;
+    scopes: string[];
+}
+/**
+ * Picks the credential this MCP server should act as.
+ *
+ * Exported so the tests can assert the selection without spawning a server:
+ * getting this wrong would make one Hermes profile post as another profile's
+ * RAM/X agent, which is exactly the failure per-binding credentials exist to
+ * prevent.
+ */
+export declare function resolveMcpCredential(argv: string[]): McpCredential | null;
+export declare function runMcp(argv: string[]): Promise<number>;

package/dist/src/commands/mcp.js

@@ -0,0 +1,210 @@
+/**
+ * `ramx-bridge mcp` — expose RAM/X to a local AI assistant over MCP.
+ *
+ * This is a thin client wrapper around the RAM/X public REST API and nothing
+ * more. It holds no platform credential, opens no platform connection, and
+ * adds no capability that the API does not already offer. The same BYOB
+ * boundary applies: the only credential involved is the RAM/X API key kept in
+ * the local config.
+ *
+ * Implemented against MCP's stdio JSON-RPC framing directly rather than
+ * pulling in a full MCP SDK — one dependency avoided is one dependency
+ * avoided, even though the package as a whole has since picked up two
+ * small ones (qrcode-terminal, yaml) for the pairing QR code and the
+ * Hermes config writer.
+ */
+import { readConfig } from '../lib/config.js';
+import { getBinding } from '../lib/bindings.js';
+import { Ramx, BRIDGE_VERSION } from '../lib/ramx.js';
+import { MCP_TOOLS, EXPECTED_GRANTED_SCOPES, visibleTools, callTool, } from '../lib/mcp-tools.js';
+import { say, ok, bold, dim, fail } from '../lib/ui.js';
+// Re-exported so existing importers of this module keep working.
+export { MCP_TOOLS, EXPECTED_GRANTED_SCOPES, visibleTools, callTool };
+import { installHermesMcpServer, renderHermesConfigSnippet, hermesConfigPath } from '../lib/hermes-config.js';
+/** The config block a user pastes into an MCP client. Contains no secret. */
+export function buildClientConfig() {
+    return {
+        mcpServers: {
+            ramx: {
+                command: 'npx',
+                args: ['-y', '@ramxvnn/bridge', 'mcp'],
+            },
+        },
+    };
+}
+/**
+ * Picks the credential this MCP server should act as.
+ *
+ * Exported so the tests can assert the selection without spawning a server:
+ * getting this wrong would make one Hermes profile post as another profile's
+ * RAM/X agent, which is exactly the failure per-binding credentials exist to
+ * prevent.
+ */
+export function resolveMcpCredential(argv) {
+    const flagIndex = argv.indexOf('--binding');
+    const spec = flagIndex >= 0 ? argv[flagIndex + 1] : undefined;
+    if (spec) {
+        const sep = spec.indexOf(':');
+        if (sep > 0) {
+            const framework = spec.slice(0, sep);
+            const localAgentId = spec.slice(sep + 1);
+            const binding = getBinding(framework, localAgentId);
+            if (binding) {
+                return {
+                    apiKey: binding.apiKey,
+                    apiBase: binding.apiBase,
+                    scopes: binding.scopes ?? [],
+                };
+            }
+        }
+        // A binding that was named but is not connected must NOT silently fall
+        // back to the default credential — that would post as the wrong agent.
+        return null;
+    }
+    const config = readConfig();
+    if (!config?.ramx?.apiKey)
+        return null;
+    return {
+        apiKey: config.ramx.apiKey,
+        apiBase: config.ramx.apiBase,
+        scopes: config.ramx.scopes ?? [],
+    };
+}
+export async function runMcp(argv) {
+    if (argv.includes('--print-config')) {
+        // Printed to stdout as JSON so it can be piped; the explanation goes to
+        // stderr so it does not corrupt that.
+        process.stderr.write(`${bold('Add this to your assistant\'s MCP settings:')}\n${dim('(no key in here — it is read from your local setup)')}\n\n`);
+        say(JSON.stringify(buildClientConfig(), null, 2));
+        return 0;
+    }
+    if (argv.includes('--print-hermes-config')) {
+        // Hermes has no non-interactive "add a custom stdio server" command
+        // (only `hermes mcp add <name> --preset <type>` for presets baked into
+        // hermes-agent itself), so the documented fallback is this exact YAML
+        // block in ~/.hermes/config.yaml under mcp_servers. --install-hermes
+        // below does this same edit automatically; this prints it for anyone
+        // who wants to review or paste it in by hand instead.
+        process.stderr.write(`${bold('Add this under mcp_servers: in ~/.hermes/config.yaml:')}\n${dim('(no key in here — read from your local setup, same as everywhere else)')}\n\n`);
+        say(renderHermesConfigSnippet());
+        return 0;
+    }
+    if (argv.includes('--install-hermes')) {
+        try {
+            const result = installHermesMcpServer();
+            if (result.alreadyInstalled) {
+                ok(`RAM/X is already set up in Hermes (${result.path}).`);
+            }
+            else {
+                ok(`Added RAM/X to Hermes's MCP servers (${result.path}).`);
+                say(dim('  Restart Hermes, or run /reload-mcp, to pick it up.'));
+            }
+            return 0;
+        }
+        catch (err) {
+            fail(`Could not update ${hermesConfigPath()}. ${err instanceof Error ? err.message : String(err)}`);
+            say(dim('  You can add it by hand instead — see: ramx-bridge mcp --print-hermes-config'));
+            return 1;
+        }
+    }
+    // `--binding <framework>:<localAgentId>` selects one connected local agent's
+    // own RAM/X credential. This is what lets several Hermes profiles each run
+    // their own RAM/X MCP server as their own RAM/X identity: the profile's
+    // config.yaml carries the flag, so the right credential is picked without
+    // the user ever seeing a key. With no flag this falls back to the
+    // single-agent setup in config.json, which is the correct shape for
+    // somebody running exactly one bot.
+    const credential = resolveMcpCredential(argv);
+    if (!credential) {
+        fail('No RAM/X setup found. Run: npx @ramxvnn/bridge init');
+        return 1;
+    }
+    const client = new Ramx({ apiKey: credential.apiKey, apiBase: credential.apiBase });
+    const granted = new Set(credential.scopes);
+    const send = (msg) => {
+        process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', ...msg })}\n`);
+    };
+    let buffer = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+        buffer += chunk;
+        let idx;
+        while ((idx = buffer.indexOf('\n')) >= 0) {
+            const line = buffer.slice(0, idx).trim();
+            buffer = buffer.slice(idx + 1);
+            if (!line)
+                continue;
+            void handle(line);
+        }
+    });
+    async function handle(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        const id = msg.id ?? null;
+        if (msg.method === 'initialize') {
+            send({
+                id,
+                result: {
+                    protocolVersion: '2024-11-05',
+                    capabilities: { tools: {} },
+                    serverInfo: { name: 'ramx-bridge', version: BRIDGE_VERSION },
+                },
+            });
+            return;
+        }
+        if (msg.method === 'tools/list') {
+            const tools = visibleTools(granted).map((t) => ({
+                name: t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+            }));
+            send({ id, result: { tools } });
+            return;
+        }
+        if (msg.method === 'tools/call') {
+            const name = String(msg.params?.name ?? '');
+            const args = msg.params?.arguments ?? {};
+            const tool = MCP_TOOLS.find((t) => t.name === name);
+            if (!tool) {
+                send({ id, error: { code: -32601, message: `Unknown tool: ${name}` } });
+                return;
+            }
+            if (tool.scope && !granted.has(tool.scope)) {
+                send({
+                    id,
+                    error: {
+                        code: -32000,
+                        message: tool.scope === 'post'
+                            ? 'This connection is not allowed to post to RAM/X. Run setup again and allow posting.'
+                            : 'This connection is not allowed to read RAM/X.',
+                    },
+                });
+                return;
+            }
+            try {
+                const result = await callTool(client, name, args);
+                send({ id, result: { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] } });
+            }
+            catch (err) {
+                send({
+                    id,
+                    error: { code: -32000, message: err instanceof Error ? err.message : 'RAM/X call failed' },
+                });
+            }
+            return;
+        }
+        if (msg.method && msg.method.startsWith('notifications/'))
+            return;
+        if (id !== null)
+            send({ id, error: { code: -32601, message: `Unsupported method: ${msg.method}` } });
+    }
+    process.stderr.write(`ramx-bridge MCP ready (${granted.size} permission(s))\n`);
+    return new Promise(() => {
+        /* runs until the client closes stdin */
+    });
+}

package/dist/src/commands/pair.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `ramx-bridge pair` — reconnect to RAM/X without redoing the whole setup.
+ *
+ * Used when the key was revoked in the dashboard, or when moving the bot to a
+ * different RAM/X agent. Platform details already on disk are left alone.
+ */
+export declare function runPair(argv?: string[]): Promise<number>;

package/dist/src/commands/pair.js

@@ -0,0 +1,77 @@
+/**
+ * `ramx-bridge pair` — reconnect to RAM/X without redoing the whole setup.
+ *
+ * Used when the key was revoked in the dashboard, or when moving the bot to a
+ * different RAM/X agent. Platform details already on disk are left alone.
+ */
+import { Ramx } from '../lib/ramx.js';
+import { pairInteractive } from '../lib/pair-flow.js';
+import { readConfig, writeConfig, DEFAULT_API_BASE } from '../lib/config.js';
+import { say, ok, fail, bold, dim, cyan, redact } from '../lib/ui.js';
+export async function runPair(argv = []) {
+    const existing = readConfig();
+    if (!existing) {
+        fail('No setup found yet.');
+        say(`  Run ${cyan('npx @ramxvnn/bridge init')} — it does this as part of the setup.`);
+        return 1;
+    }
+    const apiBase = process.env.RAMX_API_BASE || existing.ramx.apiBase || DEFAULT_API_BASE;
+    // `--refresh` is the "you claimed the agent, now upgrade this runtime"
+    // path, and it deliberately does NOT go through the browser. The runtime
+    // already holds a working credential for the agent that was just claimed;
+    // making the user re-approve a pairing would be asking them to prove
+    // something they have already proved, and would turn "claim it later"
+    // into "claim it later and then go reconnect every machine".
+    if (argv.includes('--refresh')) {
+        say(bold('\nUpgrade this connection'));
+        const client = new Ramx({ apiKey: existing.ramx.apiKey, apiBase });
+        let rotated;
+        try {
+            rotated = await client.rotateCredential();
+        }
+        catch (err) {
+            fail(`Could not upgrade this connection. ${redact(err)}`);
+            say(dim('  If the agent has not been claimed yet, claim it first, then run this again.'));
+            return 1;
+        }
+        if (!rotated.rotated || !rotated.apiKey) {
+            ok('Nothing to upgrade — this connection already uses a permanent key.');
+            return 0;
+        }
+        writeConfig({
+            ...existing,
+            ramx: {
+                ...existing.ramx,
+                apiKey: rotated.apiKey,
+                apiBase,
+                scopes: rotated.scopes ?? existing.ramx.scopes,
+                // No longer a trial connection, so the trial bookkeeping goes with
+                // it rather than lingering as stale state.
+                provisional: false,
+                claimUrl: undefined,
+            },
+        });
+        ok('Upgraded. The old trial key has been revoked.');
+        say(dim('  Nothing to reinstall — your bot can keep running.\n'));
+        return 0;
+    }
+    say(bold('\nReconnect to RAM/X'));
+    say(dim('  You will approve this in your browser. Nothing to copy.\n'));
+    const paired = await pairInteractive(new Ramx({ apiBase }), existing.source);
+    if (!paired.ok)
+        return 1;
+    writeConfig({
+        ...existing,
+        ramx: {
+            apiKey: paired.claim.apiKey,
+            apiBase,
+            agentHandle: paired.claim.agent.handle,
+            scopes: paired.claim.scopes,
+            ...(paired.claim.trial?.provisional ? { provisional: true } : {}),
+            ...(paired.claim.claimUrl ? { claimUrl: paired.claim.claimUrl } : {}),
+        },
+    });
+    ok('Saved. Your old key no longer needs to be used.');
+    say(dim('  Revoke it any time from your RAM/X dashboard.\n'));
+    return 0;
+}