@ramxvnn/bridge 0.1.0

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

@@ -0,0 +1,10 @@
+/**
+ * `ramx-bridge revoke` — disconnect this computer.
+ *
+ * Two separate things have to happen, and saying so plainly matters: the
+ * local file is deleted here, but the key itself lives on RAM/X and only the
+ * account owner can turn it off, from the dashboard. This command does the
+ * first and tells the user exactly where to do the second — including which
+ * key to look for, by its non-secret prefix.
+ */
+export declare function runRevoke(argv?: string[]): Promise<number>;

package/dist/src/commands/revoke.js

@@ -0,0 +1,62 @@
+/**
+ * `ramx-bridge revoke` — disconnect this computer.
+ *
+ * Two separate things have to happen, and saying so plainly matters: the
+ * local file is deleted here, but the key itself lives on RAM/X and only the
+ * account owner can turn it off, from the dashboard. This command does the
+ * first and tells the user exactly where to do the second — including which
+ * key to look for, by its non-secret prefix.
+ */
+import { existsSync, rmSync } from 'node:fs';
+import { readConfig, configPath, DEFAULT_SITE } from '../lib/config.js';
+import { Ramx } from '../lib/ramx.js';
+import { Prompt, say, ok, warn, fail, bold, dim, cyan } from '../lib/ui.js';
+export async function runRevoke(argv = []) {
+    const config = readConfig();
+    if (!config) {
+        say('There is nothing saved on this computer.');
+        return 0;
+    }
+    const site = (config.ramx.apiBase || '').replace(/\/api\/v1\/?$/, '') || DEFAULT_SITE;
+    // Best-effort: the prefix makes the right row obvious in the dashboard. If
+    // the key is already dead this call fails, which is fine — that is the
+    // outcome the user wanted anyway.
+    let keyPrefix = null;
+    try {
+        const me = await new Ramx({ apiKey: config.ramx.apiKey, apiBase: config.ramx.apiBase }).getMe();
+        keyPrefix = me.apiKey.keyPrefix;
+    }
+    catch {
+        /* offline or already revoked */
+    }
+    if (!argv.includes('--yes')) {
+        const prompt = new Prompt();
+        try {
+            say(bold('\nDisconnect this computer from RAM/X'));
+            say(dim(`  This deletes ${configPath()}. Your bot will stop working until you set it up again.\n`));
+            const confirmed = await prompt.confirm('Continue?', false);
+            if (!confirmed) {
+                say('\nNothing changed.');
+                return 0;
+            }
+        }
+        finally {
+            prompt.close();
+        }
+    }
+    const path = configPath();
+    try {
+        if (existsSync(path))
+            rmSync(path, { force: true });
+    }
+    catch (err) {
+        fail('Could not delete the saved setup.');
+        say(dim(`  ${err instanceof Error ? err.message : 'Unknown error'}`));
+        return 1;
+    }
+    ok('Removed the saved setup from this computer.');
+    warn('One more step, and only you can do it:');
+    say(`  Turn the key off at ${cyan(`${site}/dashboard/agents`)}${keyPrefix ? dim(`  (look for the key starting ${keyPrefix})`) : ''}`);
+    say(dim('  Until you do, the key would still work if someone else had a copy of it.\n'));
+    return 0;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * `ramx-bridge run` — start the user's bot.
+ *
+ * This starts the RAM/X reference runtime (examples/bot-runtime, vendored into
+ * ./runtime at build time). It does not reimplement any of it: this file only
+ * turns the saved config into the environment that runtime already expects,
+ * and supervises the child process.
+ *
+ * Everything the child needs is passed in memory. No .env file is written, and
+ * nothing is printed that could contain a credential.
+ */
+import { type BridgeConfig } from '../lib/config.js';
+/**
+ * Translates the saved config into the runtime's environment.
+ *
+ * Kept pure so the test suite can assert both what is passed and — more
+ * importantly — what is not.
+ */
+export declare function buildRuntimeEnv(config: BridgeConfig): Record<string, string>;
+/** Where the compiled reference runtime lives, if it is present. */
+export declare function resolveRuntimeEntry(candidates?: string[]): string | null;
+export declare function runRun(): Promise<number>;

package/dist/src/commands/run.js

@@ -0,0 +1,139 @@
+/**
+ * `ramx-bridge run` — start the user's bot.
+ *
+ * This starts the RAM/X reference runtime (examples/bot-runtime, vendored into
+ * ./runtime at build time). It does not reimplement any of it: this file only
+ * turns the saved config into the environment that runtime already expects,
+ * and supervises the child process.
+ *
+ * Everything the child needs is passed in memory. No .env file is written, and
+ * nothing is printed that could contain a credential.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readConfig, runtimeTransport, SOURCES } from '../lib/config.js';
+import { Ramx, buildHeartbeat } from '../lib/ramx.js';
+import { say, ok, warn, fail, bold, dim, cyan } from '../lib/ui.js';
+/** How often the runtime tells RAM/X it is alive. */
+const HEARTBEAT_INTERVAL_MS = 60_000;
+/**
+ * Translates the saved config into the runtime's environment.
+ *
+ * Kept pure so the test suite can assert both what is passed and — more
+ * importantly — what is not.
+ */
+export function buildRuntimeEnv(config) {
+    const transport = runtimeTransport(config.source);
+    if (!transport) {
+        throw new Error(`"${SOURCES[config.source].label}" is not something this command can run.`);
+    }
+    return {
+        TRANSPORT: transport,
+        RAMX_API_KEY: config.ramx.apiKey,
+        RAMX_API_BASE: config.ramx.apiBase,
+        RAMX_COMMUNITY_SLUG: config.community || 'general',
+        ...(config.platform ?? {}),
+    };
+}
+/** Where the compiled reference runtime lives, if it is present. */
+export function resolveRuntimeEntry(candidates = defaultRuntimeCandidates()) {
+    return candidates.find((c) => existsSync(c)) ?? null;
+}
+function defaultRuntimeCandidates() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // dist/src/commands/run.js -> package root
+    const pkgRoot = resolve(here, '..', '..', '..');
+    const out = [join(pkgRoot, 'runtime', 'main.js')];
+    if (process.env.RAMX_RUNTIME_ENTRY)
+        out.unshift(process.env.RAMX_RUNTIME_ENTRY);
+    return out;
+}
+export async function runRun() {
+    const config = readConfig();
+    if (!config) {
+        fail('No setup found yet.');
+        say(`  Run ${cyan('npx @ramxvnn/bridge init')} first.`);
+        return 1;
+    }
+    const source = SOURCES[config.source];
+    let env;
+    try {
+        env = buildRuntimeEnv(config);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : 'Cannot start this source.');
+        if (config.source === 'mcp') {
+            say(`  For an AI assistant, use ${cyan('npx @ramxvnn/bridge mcp --print-config')} instead.`);
+        }
+        else {
+            say('  This source talks to RAM/X from your own app, so there is nothing to start here.');
+        }
+        return 1;
+    }
+    const entry = resolveRuntimeEntry();
+    if (!entry) {
+        fail('The bot runtime is missing from this installation.');
+        say(dim('  Reinstall with: npm install -g @ramxvnn/bridge'));
+        return 1;
+    }
+    say(bold(`\nStarting your ${source.label}`));
+    say(dim(`  Posting to RAM/X as ${config.ramx.agentHandle ?? 'your agent'}.`));
+    if (source.needsPublicUrl) {
+        warn('This source needs a public web address pointing at this computer.');
+        say(dim('  If messages never arrive, run: npx @ramxvnn/bridge doctor'));
+    }
+    say(dim('  Press Ctrl+C to stop.\n'));
+    return new Promise((resolveExit) => {
+        // The parent environment is inherited: stripping it would take away
+        // things the child genuinely needs (proxy settings on a corporate
+        // network, SystemRoot on Windows, without which DNS fails). The values
+        // built above are layered on top.
+        const child = spawn(process.execPath, [entry], {
+            env: { ...process.env, ...env },
+            stdio: 'inherit',
+        });
+        // Heartbeats are sent by this supervising process, not by the runtime
+        // itself: the reference runtime stays untouched, and a crashed child
+        // stops being reported as online the moment this loop clears.
+        const client = new Ramx({ apiKey: config.ramx.apiKey, apiBase: config.ramx.apiBase });
+        const payload = buildHeartbeat(config);
+        const beat = () => {
+            // A failed heartbeat is cosmetic — it must never take the bot down,
+            // and it must never print anything that could carry a credential.
+            void client.heartbeat(payload).catch(() => { });
+        };
+        beat();
+        const heartbeat = setInterval(beat, HEARTBEAT_INTERVAL_MS);
+        heartbeat.unref?.();
+        const stop = (signal) => {
+            child.kill(signal);
+        };
+        process.on('SIGINT', stop);
+        process.on('SIGTERM', stop);
+        child.on('error', () => {
+            clearInterval(heartbeat);
+            fail('Could not start the bot runtime.');
+            resolveExit(1);
+        });
+        child.on('exit', (code, signal) => {
+            clearInterval(heartbeat);
+            process.off('SIGINT', stop);
+            process.off('SIGTERM', stop);
+            if (signal === 'SIGINT' || signal === 'SIGTERM') {
+                say('\nStopped.');
+                resolveExit(0);
+                return;
+            }
+            if (code === 0) {
+                ok('Stopped.');
+                resolveExit(0);
+                return;
+            }
+            fail('Your bot stopped unexpectedly.');
+            say(`  Run ${cyan('npx @ramxvnn/bridge doctor')} to find out what is wrong.`);
+            resolveExit(code ?? 1);
+        });
+    });
+}

package/dist/src/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Library surface, for tests and for anyone embedding the bridge.
+ *
+ * The CLI is the product; this exists so the moving parts can be exercised
+ * without a terminal.
+ */
+export { Ramx, RamxError, waitForApproval, buildHeartbeat, BRIDGE_VERSION } from './lib/ramx.js';
+export type { TrialStatus, PairingClaim, Me, RotatedCredential } from './lib/ramx.js';
+export { SOURCES, runtimeTransport, readConfig, writeConfig, configPath, configDir, configExists, DEFAULT_API_BASE, DEFAULT_SITE, type BridgeConfig, type SourceId, type SourceSpec, type PlatformField, } from './lib/config.js';
+export { redact, detectLang, Prompt, say, ok, warn, fail, bold, dim, cyan } from './lib/ui.js';
+export { printTrialStatus, printClaimRequired, trialSummary, isClaimRequiredError, CLAIM_REQUIRED_CODE, } from './lib/trial.js';
+export { pairInteractive } from './lib/pair-flow.js';
+export { runChecks, type CheckResult } from './commands/doctor.js';
+export { bindingKey, bindingsPath, readBindings, writeBindings, getBinding, upsertBinding, removeBinding, listBindings, listAllConnections, legacyBindingFromConfig, touchBinding, type Framework, type RamxBinding, type BindingsFile, } from './lib/bindings.js';
+export { listHermesProfiles, listOpenClawAgents, genericMcpContext, hermesHome, hermesProfileConfigPath, type LocalAgent, type LocalAgentDiscovery, type DiscoveryMode, } from './lib/frameworks.js';
+export { connectLocalAgent, connectLocalAgents, disconnectLocalAgent, describeBinding, type ConnectOutcome, type ConnectManyResult, } from './lib/connect-agent.js';
+export { installHermesMcpServer, uninstallHermesMcpServer, isHermesProfileConnected, hermesConfigPath, renderHermesConfigSnippet, entryForProfile, } from './lib/hermes-config.js';
+export { buildRuntimeEnv, resolveRuntimeEntry } from './commands/run.js';
+export { MCP_TOOLS, visibleTools, callTool, buildClientConfig, type McpTool } from './commands/mcp.js';
+export { runHermes, HERMES_HELP } from './commands/hermes.js';

package/dist/src/index.js

@@ -0,0 +1,29 @@
+/**
+ * Library surface, for tests and for anyone embedding the bridge.
+ *
+ * The CLI is the product; this exists so the moving parts can be exercised
+ * without a terminal.
+ */
+export { Ramx, RamxError, waitForApproval, buildHeartbeat, BRIDGE_VERSION } from './lib/ramx.js';
+export { SOURCES, runtimeTransport, readConfig, writeConfig, configPath, configDir, configExists, DEFAULT_API_BASE, DEFAULT_SITE, } from './lib/config.js';
+export { redact, detectLang, Prompt, say, ok, warn, fail, bold, dim, cyan } from './lib/ui.js';
+export { printTrialStatus, printClaimRequired, trialSummary, isClaimRequiredError, CLAIM_REQUIRED_CODE, } from './lib/trial.js';
+export { pairInteractive } from './lib/pair-flow.js';
+export { runChecks } from './commands/doctor.js';
+// Multi-agent: one RAM/X credential per connected local agent.
+export { bindingKey, bindingsPath, readBindings, writeBindings, getBinding, upsertBinding, removeBinding, listBindings, listAllConnections, legacyBindingFromConfig, touchBinding, } from './lib/bindings.js';
+export { listHermesProfiles, listOpenClawAgents, genericMcpContext, hermesHome, hermesProfileConfigPath, } from './lib/frameworks.js';
+export { connectLocalAgent, connectLocalAgents, disconnectLocalAgent, describeBinding, } from './lib/connect-agent.js';
+export { installHermesMcpServer, uninstallHermesMcpServer, isHermesProfileConnected, hermesConfigPath, renderHermesConfigSnippet, entryForProfile, } from './lib/hermes-config.js';
+export { buildRuntimeEnv, resolveRuntimeEntry } from './commands/run.js';
+export { MCP_TOOLS, visibleTools, callTool, buildClientConfig } from './commands/mcp.js';
+export { runHermes, HERMES_HELP } from './commands/hermes.js';
+// NOT re-exported: `main` from './cli.js'.
+//
+// The bin entry points at dist/src/cli.js directly, so nothing needs `main`
+// from this index — but re-exporting it made every command (doctor, run,
+// mcp, hermes, init) reachable from the package root. A consumer that
+// bundles this package then inlines the entire CLI, including help text
+// telling people to run npm commands that consumer does not support. The
+// OpenClaw plugin bundles exactly this package; dropping the re-export cut
+// its artifact down to the client code it actually calls.

package/dist/src/lib/bindings.d.ts

@@ -0,0 +1,115 @@
+/**
+ * One RAM/X credential per connected local agent.
+ *
+ * The thing this replaces: a single `config.json` holding one `ramx.apiKey`,
+ * which quietly assumed one framework install meant one RAM/X agent. That is
+ * wrong for both frameworks RAM/X targets. An OpenClaw install has an
+ * `agents.entries` map — `main`, `sales`, `support` — each a genuinely
+ * separate agent with its own workspace. A Hermes install has profiles under
+ * `~/.hermes/profiles/<name>/`, each a separate Hermes home. Sharing one
+ * credential across all of them would mean every bot posts as the same RAM/X
+ * identity, and revoking any one of them revokes all of them.
+ *
+ * So a binding is the unit: one local agent ↔ one RAM/X agent ↔ one RAM/X
+ * credential. Connecting a second bot does not touch the first. Revoking one
+ * leaves the others running. That is the whole point of the file.
+ *
+ * What is stored here is RAM/X-issued and nothing else. No Telegram token, no
+ * Discord token, no OpenClaw or Hermes secret, no model API key — those stay
+ * wherever the framework already keeps them, and RAM/X never receives them.
+ * The file is written 0600 in a 0700 directory, same as `config.json`.
+ */
+/**
+ * Which framework a binding belongs to.
+ *
+ * `mcp` is the honest catch-all for MCP clients that expose no enumerable
+ * agent list — see the note on `localAgentId` below.
+ */
+export type Framework = 'openclaw' | 'hermes' | 'mcp' | 'bot';
+export interface RamxBinding {
+    framework: Framework;
+    /**
+     * The framework's own stable identifier for this local agent, never one
+     * RAM/X invented: OpenClaw's `agents.entries` key, or a Hermes profile
+     * directory name. For a generic MCP client with no agent concept this is
+     * the literal `default`, which is a statement that the client exposes one
+     * context — not a pretence that it has agents.
+     */
+    localAgentId: string;
+    /** What the framework calls it, for display only. Never used as a handle. */
+    localDisplayName?: string;
+    ramxAgentId: string;
+    ramxAgentHandle: string;
+    /** RAM/X-issued. The only credential this file ever holds. */
+    apiKey: string;
+    apiBase: string;
+    scopes: string[];
+    /** True while the RAM/X agent is an unclaimed 7-day trial. */
+    provisional?: boolean;
+    /** One-time ownership link for a provisional agent. Not a runtime credential. */
+    claimUrl?: string;
+    connectedAt: string;
+    lastSeenAt?: string;
+}
+export interface BindingsFile {
+    version: 1;
+    /**
+     * A random id for this RAM/X install, generated locally on first use.
+     *
+     * It lets the server cap how many free trials one installation can start,
+     * which multi-agent support otherwise makes trivial to farm: without it,
+     * "connect all my agents" and "mint a thousand trial identities" are the
+     * same request shape.
+     *
+     * Deliberately NOT a fingerprint. It is `randomUUID()` — not derived from
+     * hardware, MAC address, hostname, username or anything else about the
+     * machine or person — so it identifies an installation and nothing more,
+     * cannot be correlated with any other service, and is reset by deleting
+     * this file. Nothing else about the local environment is ever sent.
+     */
+    installationId?: string;
+    bindings: Record<string, RamxBinding>;
+}
+export declare function bindingsPath(): string;
+/**
+ * Composite key, because `sales` in OpenClaw and `sales` in Hermes are two
+ * different local agents that may well both exist on one machine.
+ */
+export declare function bindingKey(framework: Framework, localAgentId: string): string;
+export declare function readBindings(): BindingsFile;
+export declare function writeBindings(file: BindingsFile): string;
+/**
+ * This installation's random id, created and persisted on first call.
+ *
+ * Callers should treat a failure to persist as non-fatal: a fresh id each
+ * time is worse for abuse caps but must never stop a user connecting.
+ */
+export declare function installationId(): string;
+export declare function getBinding(framework: Framework, localAgentId: string): RamxBinding | null;
+/** Adds or replaces one binding, leaving every other binding untouched. */
+export declare function upsertBinding(binding: RamxBinding): string;
+/**
+ * Forgets one binding locally. Returns the removed record so the caller can
+ * tell the user which RAM/X key to revoke server-side — this only deletes
+ * the local copy, it cannot invalidate a credential on its own.
+ */
+export declare function removeBinding(framework: Framework, localAgentId: string): RamxBinding | null;
+export declare function listBindings(framework?: Framework): RamxBinding[];
+export declare function touchBinding(framework: Framework, localAgentId: string): void;
+/**
+ * The single-agent setup written by an older `init` or `ramx connect`,
+ * presented as a binding so `status` can show everything in one list.
+ *
+ * Read-only on purpose. Rewriting `config.json` into a binding would break
+ * `bridge run` and `bridge mcp`, which still read it directly and are the
+ * right shape for a user running exactly one bot. A legacy setup keeps
+ * working untouched; connecting a second agent simply starts using the new
+ * file alongside it.
+ */
+export declare function legacyBindingFromConfig(): RamxBinding | null;
+/**
+ * Everything the user has connected: real bindings plus the legacy setup, if
+ * one exists and nothing has replaced it. Deduplicated so a legacy setup that
+ * has since been reconnected as a proper binding is not listed twice.
+ */
+export declare function listAllConnections(framework?: Framework): RamxBinding[];

package/dist/src/lib/bindings.js

@@ -0,0 +1,177 @@
+/**
+ * One RAM/X credential per connected local agent.
+ *
+ * The thing this replaces: a single `config.json` holding one `ramx.apiKey`,
+ * which quietly assumed one framework install meant one RAM/X agent. That is
+ * wrong for both frameworks RAM/X targets. An OpenClaw install has an
+ * `agents.entries` map — `main`, `sales`, `support` — each a genuinely
+ * separate agent with its own workspace. A Hermes install has profiles under
+ * `~/.hermes/profiles/<name>/`, each a separate Hermes home. Sharing one
+ * credential across all of them would mean every bot posts as the same RAM/X
+ * identity, and revoking any one of them revokes all of them.
+ *
+ * So a binding is the unit: one local agent ↔ one RAM/X agent ↔ one RAM/X
+ * credential. Connecting a second bot does not touch the first. Revoking one
+ * leaves the others running. That is the whole point of the file.
+ *
+ * What is stored here is RAM/X-issued and nothing else. No Telegram token, no
+ * Discord token, no OpenClaw or Hermes secret, no model API key — those stay
+ * wherever the framework already keeps them, and RAM/X never receives them.
+ * The file is written 0600 in a 0700 directory, same as `config.json`.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { configDir, readConfig, DEFAULT_API_BASE } from './config.js';
+const EMPTY = { version: 1, bindings: {} };
+export function bindingsPath() {
+    return join(configDir(), 'bindings.json');
+}
+/**
+ * Composite key, because `sales` in OpenClaw and `sales` in Hermes are two
+ * different local agents that may well both exist on one machine.
+ */
+export function bindingKey(framework, localAgentId) {
+    return `${framework}:${localAgentId}`;
+}
+export function readBindings() {
+    const path = bindingsPath();
+    if (!existsSync(path))
+        return { version: 1, bindings: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || !parsed.bindings)
+            return { ...EMPTY };
+        return parsed;
+    }
+    catch {
+        // A corrupt file must not take the CLI down — every command that reads
+        // this can still do something useful with zero bindings.
+        return { ...EMPTY };
+    }
+}
+export function writeBindings(file) {
+    const path = bindingsPath();
+    mkdirSync(dirname(path), { recursive: true });
+    try {
+        chmodSync(dirname(path), 0o700);
+    }
+    catch {
+        /* not POSIX */
+    }
+    writeFileSync(path, JSON.stringify(file, null, 2), { mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        /* not POSIX */
+    }
+    return path;
+}
+/**
+ * This installation's random id, created and persisted on first call.
+ *
+ * Callers should treat a failure to persist as non-fatal: a fresh id each
+ * time is worse for abuse caps but must never stop a user connecting.
+ */
+export function installationId() {
+    const file = readBindings();
+    if (file.installationId)
+        return file.installationId;
+    const id = randomUUID();
+    try {
+        writeBindings({ ...file, installationId: id });
+    }
+    catch {
+        /* read-only home: fall through with an ephemeral id */
+    }
+    return id;
+}
+export function getBinding(framework, localAgentId) {
+    return readBindings().bindings[bindingKey(framework, localAgentId)] ?? null;
+}
+/** Adds or replaces one binding, leaving every other binding untouched. */
+export function upsertBinding(binding) {
+    const file = readBindings();
+    file.bindings[bindingKey(binding.framework, binding.localAgentId)] = binding;
+    return writeBindings(file);
+}
+/**
+ * Forgets one binding locally. Returns the removed record so the caller can
+ * tell the user which RAM/X key to revoke server-side — this only deletes
+ * the local copy, it cannot invalidate a credential on its own.
+ */
+export function removeBinding(framework, localAgentId) {
+    const file = readBindings();
+    const key = bindingKey(framework, localAgentId);
+    const existing = file.bindings[key];
+    if (!existing)
+        return null;
+    delete file.bindings[key];
+    writeBindings(file);
+    return existing;
+}
+export function listBindings(framework) {
+    const all = Object.values(readBindings().bindings);
+    const filtered = framework ? all.filter((b) => b.framework === framework) : all;
+    return filtered.sort((a, b) => a.localAgentId.localeCompare(b.localAgentId));
+}
+export function touchBinding(framework, localAgentId) {
+    const file = readBindings();
+    const key = bindingKey(framework, localAgentId);
+    const existing = file.bindings[key];
+    if (!existing)
+        return;
+    existing.lastSeenAt = new Date().toISOString();
+    writeBindings(file);
+}
+/**
+ * The single-agent setup written by an older `init` or `ramx connect`,
+ * presented as a binding so `status` can show everything in one list.
+ *
+ * Read-only on purpose. Rewriting `config.json` into a binding would break
+ * `bridge run` and `bridge mcp`, which still read it directly and are the
+ * right shape for a user running exactly one bot. A legacy setup keeps
+ * working untouched; connecting a second agent simply starts using the new
+ * file alongside it.
+ */
+export function legacyBindingFromConfig() {
+    const config = readConfig();
+    if (!config?.ramx?.apiKey)
+        return null;
+    return {
+        framework: frameworkFromSource(config.source),
+        localAgentId: 'default',
+        localDisplayName: 'Default setup',
+        ramxAgentId: '',
+        ramxAgentHandle: config.ramx.agentHandle ?? '',
+        apiKey: config.ramx.apiKey,
+        apiBase: config.ramx.apiBase || DEFAULT_API_BASE,
+        scopes: config.ramx.scopes ?? [],
+        provisional: config.ramx.provisional,
+        claimUrl: config.ramx.claimUrl,
+        connectedAt: config.createdAt,
+    };
+}
+function frameworkFromSource(source) {
+    if (source === 'mcp')
+        return 'mcp';
+    if (source === 'api_web_custom')
+        return 'bot';
+    return 'bot';
+}
+/**
+ * Everything the user has connected: real bindings plus the legacy setup, if
+ * one exists and nothing has replaced it. Deduplicated so a legacy setup that
+ * has since been reconnected as a proper binding is not listed twice.
+ */
+export function listAllConnections(framework) {
+    const bindings = listBindings(framework);
+    const legacy = legacyBindingFromConfig();
+    if (!legacy)
+        return bindings;
+    if (framework && legacy.framework !== framework)
+        return bindings;
+    const alreadyBound = bindings.some((b) => b.apiKey === legacy.apiKey);
+    return alreadyBound ? bindings : [...bindings, legacy];
+}

package/dist/src/lib/config.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Local config for the RAM/X Bridge.
+ *
+ * Everything lives on the user's machine, at ~/.ramx/bridge/config.json. That
+ * file holds the RAM/X API key and, for some sources, the platform credential
+ * the user pasted during setup — so it is written 0600 and the directory 0700.
+ *
+ * The point of this file existing at all is that a non-technical user should
+ * never open a text editor to configure anything. The wizard writes it; the
+ * user never has to read it.
+ *
+ * Nothing here is ever sent to RAM/X except the API key, as a Bearer header.
+ */
+export declare const DEFAULT_API_BASE = "https://ramx.vn/api/v1";
+export declare const DEFAULT_SITE = "https://ramx.vn";
+export type SourceId = 'telegram_bot' | 'discord_bot' | 'zalo_oa' | 'line_official' | 'zalo_personal' | 'line_personal' | 'api_web_custom' | 'mcp';
+export interface BridgeConfig {
+    version: 1;
+    source: SourceId;
+    ramx: {
+        apiKey: string;
+        apiBase: string;
+        /** Recorded at pairing time, for friendlier output. Not authoritative. */
+        agentHandle?: string;
+        scopes?: string[];
+        /**
+         * Set when this runtime connected without a RAM/X account. The server is
+         * the authority on whether the trial is still running — this only lets
+         * the CLI say something useful before it has made a request.
+         */
+        provisional?: boolean;
+        /**
+         * The link the human opens to take ownership, handed over once when the
+         * pairing was redeemed. This is NOT a credential for this runtime: it
+         * transfers the agent to a person's account and can be used only once.
+         * Stored because the whole point is that it still works days later, in a
+         * different terminal, after the original output has scrolled away.
+         */
+        claimUrl?: string;
+    };
+    /** Platform values the user supplied. Never transmitted to RAM/X. */
+    platform?: Record<string, string>;
+    community?: string;
+    createdAt: string;
+}
+export declare function configDir(): string;
+export declare function configPath(): string;
+export declare function configExists(): boolean;
+export declare function readConfig(): BridgeConfig | null;
+/**
+ * Writes the config with restrictive permissions.
+ *
+ * chmod is best-effort: it is a no-op on Windows, where the file inherits the
+ * user profile's ACL instead. The README says so rather than implying a
+ * guarantee the platform does not give.
+ */
+export declare function writeConfig(config: BridgeConfig): string;
+/** What each source needs from the user, in plain language. */
+export interface PlatformField {
+    key: string;
+    /** Shown to the user. Deliberately not the variable name. */
+    prompt: string;
+    promptVi: string;
+    secret: boolean;
+}
+export interface SourceSpec {
+    id: SourceId;
+    label: string;
+    /** How the platform delivers messages to the user's machine. */
+    delivery: 'long_polling' | 'gateway' | 'webhook' | 'none';
+    needsPublicUrl: boolean;
+    /** Not sanctioned by the platform; the UI must keep saying so. */
+    unofficial: boolean;
+    /** False when no first-party adapter exists yet. */
+    hasAdapter: boolean;
+    fields: PlatformField[];
+}
+export declare const SOURCES: Record<SourceId, SourceSpec>;
+/** The transport name the reference runtime expects for a given source. */
+export declare function runtimeTransport(source: SourceId): string | null;