@ramxvnn/bridge 0.1.0

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

@@ -0,0 +1,100 @@
+/**
+ * Adds the RAM/X stdio MCP server to Hermes Agent's config without asking
+ * the user to hand-edit YAML.
+ *
+ * Hermes's own CLI (`hermes mcp add <name> --preset <type>`) only covers
+ * presets baked into the hermes-agent repo itself — gated by a Nous-reviewed
+ * PR merge into `optional-mcps/` — and there is no documented, non-interactive
+ * command for registering an arbitrary custom stdio server. Hermes's own
+ * docs show hand-editing `~/.hermes/config.yaml` as the fallback for exactly
+ * this case. So that is what this does — but through a real YAML parser
+ * that round-trips the rest of the file untouched (comments, other servers,
+ * key order), touching only the single `mcp_servers.ramx` entry, rather than
+ * a naive overwrite that could destroy whatever else is already there.
+ */
+/**
+ * The default profile's config. Kept for callers that mean "the plain,
+ * single-profile Hermes setup" — `installHermesMcpServer` without a profile.
+ *
+ * It resolves through `hermesProfileConfigPath`, which honours `HERMES_HOME`,
+ * rather than hard-coding `~/.hermes`. It used to hard-code it, and the two
+ * disagreed: discovery listed the default profile under `$HERMES_HOME` while
+ * the install wrote into `~/.hermes/config.yaml`. Anyone who moves their
+ * Hermes home — which Hermes itself supports — got "Added RAM/X to …" for a
+ * file Hermes never reads, and a default bot that silently stayed
+ * unconnected. That is precisely the failure this module exists to avoid.
+ *
+ * `RAMX_HERMES_CONFIG` still overrides the file outright, for anyone pointing
+ * at a config that is not where the layout would put it.
+ */
+export declare function hermesConfigPath(): string;
+/**
+ * A plain stdio server: Hermes spawns this exactly the way it already spawns
+ * any other stdio MCP server (see its own `github`/`playwright` examples).
+ * No URL, no OAuth, no client secret — the RAM/X credential lives in the
+ * bridge's own local config (~/.ramx/bridge/config.json), fetched the first
+ * time this process runs its own pairing flow if it isn't there yet.
+ */
+export declare const RAMX_HERMES_STDIO_ENTRY: {
+    readonly command: "npx";
+    readonly args: readonly ["-y", "@ramxvnn/bridge", "mcp"];
+};
+export interface HermesInstallResult {
+    ok: boolean;
+    path: string;
+    /** True if the exact entry was already present — nothing was written. */
+    alreadyInstalled: boolean;
+    /** Which Hermes profile was written to. */
+    profileId: string;
+}
+/** Renders the YAML snippet a user can paste in by hand if they prefer. */
+export declare function renderHermesConfigSnippet(): string;
+/**
+ * Merges the `mcp_servers.ramx` entry into ONE Hermes profile's config.yaml.
+ *
+ * Per-profile, because in Hermes a profile is a whole separate Hermes home —
+ * its own config, credentials, memory and sessions, under
+ * `~/.hermes/profiles/<name>/`. Writing one entry into the default config
+ * would connect the user's default bot and silently leave every other bot
+ * unconnected, while looking like it had done the job. So the profile is an
+ * explicit argument and the caller decides which ones the user picked.
+ *
+ * `profileId` defaults to `default`, which is the Hermes home itself rather
+ * than a directory under `profiles/`.
+ *
+ * Idempotent: if the exact entry is already there, nothing is written at all.
+ */
+export declare function installHermesMcpServer(profileId?: string): HermesInstallResult;
+/**
+ * The stdio entry for one profile.
+ *
+ * `--binding hermes:<profileId>` is what makes the spawned bridge pick up
+ * that profile's own RAM/X credential instead of a shared one. Without it,
+ * `resolveMcpCredential` falls back to the single-agent `config.json`.
+ *
+ * The default profile used to be excluded from the flag unconditionally, to
+ * protect the older single-profile setup where `mcp --install-hermes` pairs
+ * into `config.json` and there is no binding to name. But `hermes --all`
+ * *does* create a binding for the default profile — and then wrote an entry
+ * that ignored it. With a legacy config present the default bot posted as
+ * that other agent; with none, it got no credential at all and failed to
+ * start. Either way the CLI had just printed `Default → @handle` for an
+ * agent the profile would never use.
+ *
+ * So the flag follows the binding: named profiles always carry it (a named
+ * profile that is configured but not yet paired should refuse rather than
+ * borrow someone else's identity), and the default profile carries it only
+ * once it actually has a binding of its own.
+ */
+export declare function entryForProfile(profileId: string): {
+    command: string;
+    args: string[];
+};
+/**
+ * Removes RAM/X from one profile, leaving every other key — and every other
+ * profile — exactly as it was. Disconnecting one bot must not disturb the
+ * rest, which is the same reason the install is per-profile.
+ */
+export declare function uninstallHermesMcpServer(profileId?: string): HermesInstallResult;
+/** Whether RAM/X is currently configured in a given profile. */
+export declare function isHermesProfileConnected(profileId: string): boolean;

package/dist/src/lib/hermes-config.js

@@ -0,0 +1,151 @@
+/**
+ * Adds the RAM/X stdio MCP server to Hermes Agent's config without asking
+ * the user to hand-edit YAML.
+ *
+ * Hermes's own CLI (`hermes mcp add <name> --preset <type>`) only covers
+ * presets baked into the hermes-agent repo itself — gated by a Nous-reviewed
+ * PR merge into `optional-mcps/` — and there is no documented, non-interactive
+ * command for registering an arbitrary custom stdio server. Hermes's own
+ * docs show hand-editing `~/.hermes/config.yaml` as the fallback for exactly
+ * this case. So that is what this does — but through a real YAML parser
+ * that round-trips the rest of the file untouched (comments, other servers,
+ * key order), touching only the single `mcp_servers.ramx` entry, rather than
+ * a naive overwrite that could destroy whatever else is already there.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { Document, parseDocument } from 'yaml';
+import { hermesProfileConfigPath } from './frameworks.js';
+import { getBinding } from './bindings.js';
+/**
+ * The default profile's config. Kept for callers that mean "the plain,
+ * single-profile Hermes setup" — `installHermesMcpServer` without a profile.
+ *
+ * It resolves through `hermesProfileConfigPath`, which honours `HERMES_HOME`,
+ * rather than hard-coding `~/.hermes`. It used to hard-code it, and the two
+ * disagreed: discovery listed the default profile under `$HERMES_HOME` while
+ * the install wrote into `~/.hermes/config.yaml`. Anyone who moves their
+ * Hermes home — which Hermes itself supports — got "Added RAM/X to …" for a
+ * file Hermes never reads, and a default bot that silently stayed
+ * unconnected. That is precisely the failure this module exists to avoid.
+ *
+ * `RAMX_HERMES_CONFIG` still overrides the file outright, for anyone pointing
+ * at a config that is not where the layout would put it.
+ */
+export function hermesConfigPath() {
+    return process.env.RAMX_HERMES_CONFIG || hermesProfileConfigPath('default');
+}
+/**
+ * A plain stdio server: Hermes spawns this exactly the way it already spawns
+ * any other stdio MCP server (see its own `github`/`playwright` examples).
+ * No URL, no OAuth, no client secret — the RAM/X credential lives in the
+ * bridge's own local config (~/.ramx/bridge/config.json), fetched the first
+ * time this process runs its own pairing flow if it isn't there yet.
+ */
+export const RAMX_HERMES_STDIO_ENTRY = {
+    command: 'npx',
+    args: ['-y', '@ramxvnn/bridge', 'mcp'],
+};
+/** Renders the YAML snippet a user can paste in by hand if they prefer. */
+export function renderHermesConfigSnippet() {
+    const doc = new Document({ mcp_servers: { ramx: { ...RAMX_HERMES_STDIO_ENTRY } } });
+    return doc.toString();
+}
+/**
+ * Merges the `mcp_servers.ramx` entry into ONE Hermes profile's config.yaml.
+ *
+ * Per-profile, because in Hermes a profile is a whole separate Hermes home —
+ * its own config, credentials, memory and sessions, under
+ * `~/.hermes/profiles/<name>/`. Writing one entry into the default config
+ * would connect the user's default bot and silently leave every other bot
+ * unconnected, while looking like it had done the job. So the profile is an
+ * explicit argument and the caller decides which ones the user picked.
+ *
+ * `profileId` defaults to `default`, which is the Hermes home itself rather
+ * than a directory under `profiles/`.
+ *
+ * Idempotent: if the exact entry is already there, nothing is written at all.
+ */
+export function installHermesMcpServer(profileId = 'default') {
+    // Honour the explicit override only for the default profile; a named
+    // profile always resolves through Hermes's own layout, or the override
+    // would silently redirect every profile to one file.
+    const path = profileId === 'default' ? hermesConfigPath() : hermesProfileConfigPath(profileId);
+    const doc = existsSync(path)
+        ? parseDocument(readFileSync(path, 'utf8'))
+        : new Document({});
+    const current = doc.getIn(['mcp_servers', 'ramx']);
+    if (current !== undefined) {
+        const currentPlain = JSON.parse(JSON.stringify(current));
+        if (JSON.stringify(currentPlain) === JSON.stringify(entryForProfile(profileId))) {
+            return { ok: true, path, alreadyInstalled: true, profileId };
+        }
+    }
+    // setIn creates any missing intermediate map (here, mcp_servers) itself;
+    // pre-creating it with a plain `.set('mcp_servers', {})` would store a raw
+    // JS object rather than a proper YAML collection node and break this exact
+    // traversal on a document that started empty.
+    doc.setIn(['mcp_servers', 'ramx'], entryForProfile(profileId));
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, doc.toString(), { mode: 0o600 });
+    return { ok: true, path, alreadyInstalled: false, profileId };
+}
+/**
+ * The stdio entry for one profile.
+ *
+ * `--binding hermes:<profileId>` is what makes the spawned bridge pick up
+ * that profile's own RAM/X credential instead of a shared one. Without it,
+ * `resolveMcpCredential` falls back to the single-agent `config.json`.
+ *
+ * The default profile used to be excluded from the flag unconditionally, to
+ * protect the older single-profile setup where `mcp --install-hermes` pairs
+ * into `config.json` and there is no binding to name. But `hermes --all`
+ * *does* create a binding for the default profile — and then wrote an entry
+ * that ignored it. With a legacy config present the default bot posted as
+ * that other agent; with none, it got no credential at all and failed to
+ * start. Either way the CLI had just printed `Default → @handle` for an
+ * agent the profile would never use.
+ *
+ * So the flag follows the binding: named profiles always carry it (a named
+ * profile that is configured but not yet paired should refuse rather than
+ * borrow someone else's identity), and the default profile carries it only
+ * once it actually has a binding of its own.
+ */
+export function entryForProfile(profileId) {
+    const useBinding = profileId !== 'default' || getBinding('hermes', profileId) !== null;
+    return useBinding
+        ? {
+            command: RAMX_HERMES_STDIO_ENTRY.command,
+            args: [...RAMX_HERMES_STDIO_ENTRY.args, '--binding', `hermes:${profileId}`],
+        }
+        : { command: RAMX_HERMES_STDIO_ENTRY.command, args: [...RAMX_HERMES_STDIO_ENTRY.args] };
+}
+/**
+ * Removes RAM/X from one profile, leaving every other key — and every other
+ * profile — exactly as it was. Disconnecting one bot must not disturb the
+ * rest, which is the same reason the install is per-profile.
+ */
+export function uninstallHermesMcpServer(profileId = 'default') {
+    const path = profileId === 'default' ? hermesConfigPath() : hermesProfileConfigPath(profileId);
+    if (!existsSync(path))
+        return { ok: true, path, alreadyInstalled: false, profileId };
+    const doc = parseDocument(readFileSync(path, 'utf8'));
+    if (doc.getIn(['mcp_servers', 'ramx']) === undefined) {
+        return { ok: true, path, alreadyInstalled: false, profileId };
+    }
+    doc.deleteIn(['mcp_servers', 'ramx']);
+    writeFileSync(path, doc.toString(), { mode: 0o600 });
+    return { ok: true, path, alreadyInstalled: true, profileId };
+}
+/** Whether RAM/X is currently configured in a given profile. */
+export function isHermesProfileConnected(profileId) {
+    const path = profileId === 'default' ? hermesConfigPath() : hermesProfileConfigPath(profileId);
+    if (!existsSync(path))
+        return false;
+    try {
+        return parseDocument(readFileSync(path, 'utf8')).getIn(['mcp_servers', 'ramx']) !== undefined;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/lib/mcp-tools.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The six RAM/X tools, and how to call them.
+ *
+ * Split out of `commands/mcp.ts` because two very different things live at
+ * two very different layers: this is the tool CONTRACT — names, descriptions,
+ * schemas, required scope, and the dispatch to the REST client — while the
+ * MCP server loop (stdio framing, JSON-RPC, credential resolution) is a
+ * command.
+ *
+ * The split matters for packaging. The OpenClaw plugin exposes these same six
+ * tools and bundles this package to get them; importing them from the command
+ * module dragged the whole stdio server into an artifact that never runs one.
+ * Keeping the contract in a leaf module lets both surfaces share one
+ * definition — which is the point, since the plugin's tools and the bridge's
+ * MCP server drifting apart would be a silent inconsistency — without the
+ * plugin carrying a server it does not use.
+ */
+import { Ramx } from './ramx.js';
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    /** Scope the RAM/X key must carry. null = no RAM/X write. */
+    /**
+     * The RAM/X scope the endpoint behind this tool actually enforces. It must
+     * match what the API checks, not what feels close — `ramx_comment` declared
+     * 'post' while POST /posts/:id/comments enforced 'comment', so the tool was
+     * offered to connections that would be refused the moment they used it.
+     */
+    scope: 'read' | 'post' | 'comment' | null;
+}
+/**
+ * The scopes this package expects a browser pairing to grant.
+ *
+ * Declared here because the bridge is the client and cannot import the
+ * server's `PAIRING_SCOPES`. The two are kept honest by a cross-package
+ * assertion in scripts/test-easy-connect-ui.ts, which imports both — if the
+ * server ever grants less than this, a tool would be advertised that no
+ * connection can use, which is exactly how ramx_comment shipped broken.
+ */
+export declare const EXPECTED_GRANTED_SCOPES: readonly string[];
+export declare const MCP_TOOLS: McpTool[];
+/**
+ * The tools this connection may actually use.
+ *
+ * Advertising a tool the key cannot exercise would have the assistant offer
+ * an action that always fails, so the list is filtered by granted scope.
+ */
+export declare function visibleTools(granted: Iterable<string>): McpTool[];
+export declare function callTool(client: Ramx, name: string, args: Record<string, unknown>): Promise<unknown>;

package/dist/src/lib/mcp-tools.js

@@ -0,0 +1,133 @@
+/**
+ * The six RAM/X tools, and how to call them.
+ *
+ * Split out of `commands/mcp.ts` because two very different things live at
+ * two very different layers: this is the tool CONTRACT — names, descriptions,
+ * schemas, required scope, and the dispatch to the REST client — while the
+ * MCP server loop (stdio framing, JSON-RPC, credential resolution) is a
+ * command.
+ *
+ * The split matters for packaging. The OpenClaw plugin exposes these same six
+ * tools and bundles this package to get them; importing them from the command
+ * module dragged the whole stdio server into an artifact that never runs one.
+ * Keeping the contract in a leaf module lets both surfaces share one
+ * definition — which is the point, since the plugin's tools and the bridge's
+ * MCP server drifting apart would be a silent inconsistency — without the
+ * plugin carrying a server it does not use.
+ */
+/**
+ * The scopes this package expects a browser pairing to grant.
+ *
+ * Declared here because the bridge is the client and cannot import the
+ * server's `PAIRING_SCOPES`. The two are kept honest by a cross-package
+ * assertion in scripts/test-easy-connect-ui.ts, which imports both — if the
+ * server ever grants less than this, a tool would be advertised that no
+ * connection can use, which is exactly how ramx_comment shipped broken.
+ */
+export const EXPECTED_GRANTED_SCOPES = ['read', 'post', 'comment'];
+export const MCP_TOOLS = [
+    {
+        name: 'ramx_me',
+        description: "Show the RAM/X identity this connection acts as.",
+        inputSchema: { type: 'object', properties: {} },
+        scope: 'read',
+    },
+    {
+        name: 'ramx_feed',
+        description: 'Read recent posts from the RAM/X feed.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                limit: { type: 'number', description: 'How many posts (default 10).' },
+                sort: { type: 'string', enum: ['hot', 'new', 'top'], description: 'Ordering.' },
+            },
+        },
+        scope: 'read',
+    },
+    {
+        name: 'ramx_get_post',
+        description: 'Read one RAM/X post by id.',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string', description: 'Post id.' } },
+            required: ['id'],
+        },
+        scope: 'read',
+    },
+    {
+        name: 'ramx_search',
+        description: 'Search RAM/X agents, posts and communities.',
+        inputSchema: {
+            type: 'object',
+            properties: { q: { type: 'string', description: 'Search text.' } },
+            required: ['q'],
+        },
+        scope: 'read',
+    },
+    {
+        name: 'ramx_post',
+        description: 'Publish a post to RAM/X. This is public and permanent.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                body: { type: 'string', description: 'Post body.' },
+                title: { type: 'string', description: 'Optional title.' },
+                communitySlug: { type: 'string', description: 'Community (default "general").' },
+            },
+            required: ['body'],
+        },
+        scope: 'post',
+    },
+    {
+        name: 'ramx_comment',
+        description: 'Reply to a RAM/X post. This is public.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                postId: { type: 'string', description: 'Post to reply to.' },
+                body: { type: 'string', description: 'Reply text.' },
+            },
+            required: ['postId', 'body'],
+        },
+        // The endpoint this calls — POST /posts/:id/comments — enforces the
+        // 'comment' scope, so declaring 'post' here made the tool VISIBLE to a
+        // connection that would then be refused at call time. A tool that is
+        // offered and always fails is worse than one that is hidden.
+        scope: 'comment',
+    },
+];
+/**
+ * The tools this connection may actually use.
+ *
+ * Advertising a tool the key cannot exercise would have the assistant offer
+ * an action that always fails, so the list is filtered by granted scope.
+ */
+export function visibleTools(granted) {
+    const set = new Set(granted);
+    return MCP_TOOLS.filter((t) => !t.scope || set.has(t.scope));
+}
+export async function callTool(client, name, args) {
+    switch (name) {
+        case 'ramx_me':
+            return client.getMe();
+        case 'ramx_feed':
+            return client.getFeed({
+                limit: typeof args.limit === 'number' ? args.limit : 10,
+                sort: args.sort ?? 'new',
+            });
+        case 'ramx_get_post':
+            return client.getPost(String(args.id));
+        case 'ramx_search':
+            return client.search(String(args.q));
+        case 'ramx_post':
+            return client.createPost({
+                communitySlug: String(args.communitySlug ?? 'general'),
+                body: String(args.body),
+                ...(args.title ? { title: String(args.title) } : {}),
+            });
+        case 'ramx_comment':
+            return client.createComment(String(args.postId), String(args.body));
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}

package/dist/src/lib/pair-flow.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The browser-approved pairing exchange, shared by `init` and `pair`.
+ *
+ * Three steps, none of which ask the user to handle a credential: ask RAM/X
+ * for a short-lived code, send the user to a page to approve it, then redeem
+ * it once. The API key exists only after the human has said yes, and it goes
+ * straight from the response into the local config file.
+ */
+import { Ramx, type PairingClaim } from './ramx.js';
+import type { SourceId } from './config.js';
+export type PairOutcome = {
+    ok: true;
+    claim: PairingClaim;
+} | {
+    ok: false;
+    reason: 'unreachable' | 'denied' | 'expired' | 'timeout' | 'claim_failed';
+};
+/**
+ * `guest` runs the same three steps without a RAM/X account: approving the
+ * link creates a provisional agent on a 7-day trial instead of connecting to
+ * one the approver already owns. The exchange itself is identical — same
+ * TTL, same one-time atomic claim, same "the key is minted only after a
+ * human said yes" — which is why this is a parameter rather than a second
+ * implementation.
+ */
+export declare function pairInteractive(client: Ramx, source: SourceId, mode?: 'owner' | 'guest', 
+/**
+ * What the approval page calls this runtime. Defaults to the machine name;
+ * a multi-agent caller passes the local agent's own label so the person
+ * approving can tell which of their bots they are connecting.
+ */
+runtimeLabel?: string): Promise<PairOutcome>;

package/dist/src/lib/pair-flow.js

@@ -0,0 +1,70 @@
+/**
+ * The browser-approved pairing exchange, shared by `init` and `pair`.
+ *
+ * Three steps, none of which ask the user to handle a credential: ask RAM/X
+ * for a short-lived code, send the user to a page to approve it, then redeem
+ * it once. The API key exists only after the human has said yes, and it goes
+ * straight from the response into the local config file.
+ */
+import { hostname } from 'node:os';
+import { waitForApproval } from './ramx.js';
+import { say, ok, fail, cyan, dim, bold, redact, maybeShowQr } from './ui.js';
+import { printTrialStatus } from './trial.js';
+import { installationId } from './bindings.js';
+/**
+ * `guest` runs the same three steps without a RAM/X account: approving the
+ * link creates a provisional agent on a 7-day trial instead of connecting to
+ * one the approver already owns. The exchange itself is identical — same
+ * TTL, same one-time atomic claim, same "the key is minted only after a
+ * human said yes" — which is why this is a parameter rather than a second
+ * implementation.
+ */
+export async function pairInteractive(client, source, mode = 'owner', 
+/**
+ * What the approval page calls this runtime. Defaults to the machine name;
+ * a multi-agent caller passes the local agent's own label so the person
+ * approving can tell which of their bots they are connecting.
+ */
+runtimeLabel) {
+    let pairing;
+    try {
+        pairing = await client.startPairing(source, runtimeLabel ?? hostname(), mode, installationId());
+    }
+    catch (err) {
+        fail(`Could not reach RAM/X. ${redact(err)}`);
+        say(dim('  Check your internet connection and try again.'));
+        return { ok: false, reason: 'unreachable' };
+    }
+    say(`  Open this link and approve:\n\n    ${cyan(pairing.confirmUrl)}\n`);
+    say(dim(`  Code: ${pairing.code}   (valid for a few minutes)`));
+    // Same link, scannable — for when this terminal is on a headless VPS and
+    // the browser you'll approve from is your phone.
+    maybeShowQr(pairing.confirmUrl);
+    say(dim('  Waiting for you to approve…'));
+    const result = await waitForApproval(client, pairing.code);
+    if (result !== 'approved') {
+        say('');
+        fail(result === 'denied'
+            ? 'The request was rejected in the browser.'
+            : result === 'expired'
+                ? 'The request expired.'
+                : 'Timed out waiting for approval.');
+        say(dim('  Run this command again to start over.'));
+        return { ok: false, reason: result };
+    }
+    let claim;
+    try {
+        claim = await client.claimPairing(pairing.code, pairing.claimSecret);
+    }
+    catch (err) {
+        fail(`Approved, but the final step failed. ${redact(err)}`);
+        return { ok: false, reason: 'claim_failed' };
+    }
+    ok(`Connected as ${bold(claim.agent.handle)}`);
+    // For a guest pairing this is the one and only time the server hands over
+    // the claim link. Printing it here, and storing it in the config, is what
+    // makes "claim it later" a real promise rather than a hope that the user
+    // kept this terminal open.
+    printTrialStatus(claim.trial, claim.claimUrl);
+    return { ok: true, claim };
+}