@ramxvnn/bridge 0.1.0 → 0.1.1

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

@@ -5,15 +5,48 @@
  * non-technical user who sees "403" learns nothing; "this key cannot post,
  * reconnect and allow posting" they can act on.
  *
+ * There are two shapes of setup on disk, and doctor has to understand both:
+ *
+ *   - the LEGACY single-agent setup in `config.json`, which assumed one
+ *     framework install meant one RAM/X agent;
+ *   - the per-binding credentials in `bindings.json`, one RAM/X agent per
+ *     OpenClaw agent or Hermes profile.
+ *
+ * It used to read only the first. Anyone who connected through
+ * `openclaw ramx connect` or `ramx-bridge hermes` — the flows this product
+ * actually leads with — was told "No setup found on this computer", and then
+ * told to run `init`, a single-agent command that is the wrong fix for them.
+ * Their credentials were sitting in `bindings.json` the whole time.
+ *
+ * Each binding is checked with ITS OWN credential and nothing else. That is
+ * the same fail-closed rule `resolveMcpCredential` follows, and for the same
+ * reason: a binding that borrowed another's key would report healthy while
+ * the agent it names is broken. One failing binding must not stop the others
+ * being checked either — a user with four bots wants all four verdicts.
+ *
  * No secret is printed, not even partially.
  */
 import { Ramx } from '../lib/ramx.js';
+import { type RamxBinding } from '../lib/bindings.js';
 export interface CheckResult {
     name: string;
     status: 'ok' | 'fail' | 'warn';
     detail: string;
     fix?: string;
+    /**
+     * Which setup this check belongs to — "OpenClaw", "Hermes", "Legacy setup".
+     * Absent for checks about the machine as a whole.
+     */
+    group?: string;
 }
-/** Pure so the tests can assert the diagnosis without a terminal. */
-export declare function runChecks(client?: Ramx): Promise<CheckResult[]>;
+/** Test seam: each binding gets its own client, never a shared one. */
+export type ClientFactory = (binding: RamxBinding) => Ramx;
+/**
+ * Pure so the tests can assert the diagnosis without a terminal.
+ *
+ * `client` stands in for the network on the LEGACY config path only.
+ * `makeClient` does the same per binding. A binding never borrows `client`;
+ * see the module note.
+ */
+export declare function runChecks(client?: Ramx, makeClient?: ClientFactory): Promise<CheckResult[]>;
 export declare function runDoctor(): Promise<number>;

package/dist/src/commands/doctor.js

@@ -5,17 +5,242 @@
  * non-technical user who sees "403" learns nothing; "this key cannot post,
  * reconnect and allow posting" they can act on.
  *
+ * There are two shapes of setup on disk, and doctor has to understand both:
+ *
+ *   - the LEGACY single-agent setup in `config.json`, which assumed one
+ *     framework install meant one RAM/X agent;
+ *   - the per-binding credentials in `bindings.json`, one RAM/X agent per
+ *     OpenClaw agent or Hermes profile.
+ *
+ * It used to read only the first. Anyone who connected through
+ * `openclaw ramx connect` or `ramx-bridge hermes` — the flows this product
+ * actually leads with — was told "No setup found on this computer", and then
+ * told to run `init`, a single-agent command that is the wrong fix for them.
+ * Their credentials were sitting in `bindings.json` the whole time.
+ *
+ * Each binding is checked with ITS OWN credential and nothing else. That is
+ * the same fail-closed rule `resolveMcpCredential` follows, and for the same
+ * reason: a binding that borrowed another's key would report healthy while
+ * the agent it names is broken. One failing binding must not stop the others
+ * being checked either — a user with four bots wants all four verdicts.
+ *
  * No secret is printed, not even partially.
  */
 import { Ramx } from '../lib/ramx.js';
 import { readConfig, configPath, SOURCES, runtimeTransport } from '../lib/config.js';
+import { listBindings, bindingsPath } from '../lib/bindings.js';
 import { say, ok, fail, warn, bold, dim, cyan, redact } from '../lib/ui.js';
-import { trialSummary } from '../lib/trial.js';
-/** Pure so the tests can assert the diagnosis without a terminal. */
-export async function runChecks(client) {
+import { trialSummary, isClaimRequiredError } from '../lib/trial.js';
+const FRAMEWORK_LABEL = {
+    openclaw: 'OpenClaw',
+    hermes: 'Hermes',
+    mcp: 'MCP client',
+    bot: 'Bot / custom runtime',
+};
+/** What to call this binding on screen. Never the RAM/X handle alone. */
+function bindingLabel(b) {
+    const local = b.localDisplayName?.trim() || b.localAgentId;
+    return b.framework === 'hermes' ? `${local} (profile)` : local;
+}
+/** The command that reconnects THIS binding, and only this one. */
+function reconnectFix(b) {
+    if (b.framework === 'openclaw') {
+        return `Reconnect just this agent: openclaw ramx connect --agent ${b.localAgentId}`;
+    }
+    if (b.framework === 'hermes') {
+        return `Reconnect just this profile: npx @ramxvnn/bridge hermes --profile ${b.localAgentId}`;
+    }
+    return 'Reconnect this runtime: npx @ramxvnn/bridge init';
+}
+/**
+ * Turns a failed call into something the reader can act on.
+ *
+ * The distinctions matter: 401 means the credential is gone, 403 means it is
+ * valid but not allowed, 429 means nothing is wrong at all, and a network
+ * error means we learned nothing about the credential either way. Collapsing
+ * them into "auth failed" sends people to reconnect a binding that is fine.
+ */
+function diagnose(err, subject, fixWhenRejected) {
+    const e = err;
+    if (isClaimRequiredError(err)) {
+        return {
+            name: subject,
+            status: 'fail',
+            detail: 'The 7-day trial has ended and nobody has claimed this agent.',
+            fix: 'Claim it to start posting again: https://ramx.vn/claim',
+        };
+    }
+    if (e?.isAuth) {
+        return {
+            name: subject,
+            status: 'fail',
+            detail: 'RAM/X no longer accepts this connection — the key was revoked or removed.',
+            fix: fixWhenRejected,
+        };
+    }
+    if (e?.isScope) {
+        return {
+            name: subject,
+            status: 'fail',
+            detail: 'This connection is not allowed to do that.',
+            fix: fixWhenRejected,
+        };
+    }
+    if (e?.isRateLimited) {
+        return {
+            name: subject,
+            status: 'warn',
+            detail: 'RAM/X is rate-limiting this computer right now. Nothing is wrong with the connection.',
+            fix: e.retryAfterSeconds
+                ? `Wait about ${e.retryAfterSeconds}s and run this again.`
+                : 'Wait a minute and run this again.',
+        };
+    }
+    return {
+        name: subject,
+        status: 'fail',
+        detail: `Could not reach RAM/X. ${redact(err)}`,
+        fix: 'Check your internet connection, then try again.',
+    };
+}
+/**
+ * The claim link, with its one-time token removed.
+ *
+ * `claimUrl` carries `?token=ramx_claim_…`, and that token TRANSFERS
+ * OWNERSHIP of the agent to whoever opens it. Every other surface that
+ * prints it — the connect flow, `status` — is showing it once to the person
+ * who just connected. Doctor is different: it is the output people paste
+ * into bug reports and support threads, which is exactly why the server
+ * refuses to put this token in API error bodies. So doctor shows the landing
+ * page and says where the full link lives.
+ */
+function claimLinkForDisplay(claimUrl) {
+    if (!claimUrl)
+        return 'https://ramx.vn/claim';
+    try {
+        const u = new URL(claimUrl);
+        return `${u.origin}${u.pathname}`;
+    }
+    catch {
+        return 'https://ramx.vn/claim';
+    }
+}
+/** The trial/ownership line for one connection, or nothing for an owned agent. */
+function ownershipCheck(me, claimUrl, group) {
+    if (me.trial?.provisional) {
+        const link = claimLinkForDisplay(claimUrl);
+        const where = claimUrl
+            ? ' Your one-time claim link was shown when you connected.'
+            : '';
+        return me.trial.expired
+            ? {
+                name: 'Ownership',
+                status: 'fail',
+                detail: 'The 7-day trial has ended and nobody has claimed this agent.',
+                fix: `Claim it to start posting again: ${link}.${where}`,
+                ...(group ? { group } : {}),
+            }
+            : {
+                name: 'Ownership',
+                status: 'warn',
+                detail: `Unclaimed — trial, ${trialSummary(me.trial)}.`,
+                fix: `Claim it any time to keep it: ${link}.${where}`,
+                ...(group ? { group } : {}),
+            };
+    }
+    if (me.ownerBound) {
+        return { name: 'Ownership', status: 'ok', detail: 'Claimed', ...(group ? { group } : {}) };
+    }
+    return null;
+}
+/**
+ * Checks one binding with its own credential.
+ *
+ * Never falls back to another binding's key, and never to `config.json`: a
+ * named binding that cannot authenticate must fail, not quietly succeed as
+ * somebody else.
+ */
+async function checkBinding(b, makeClient) {
+    const group = FRAMEWORK_LABEL[b.framework] ?? b.framework;
+    const label = bindingLabel(b);
+    const out = [];
+    if (!b.apiKey) {
+        out.push({
+            name: label,
+            status: 'fail',
+            detail: 'This connection has no RAM/X key saved.',
+            fix: reconnectFix(b),
+            group,
+        });
+        return out;
+    }
+    const client = makeClient
+        ? makeClient(b)
+        : new Ramx({ apiKey: b.apiKey, apiBase: b.apiBase });
+    let me;
+    try {
+        me = await client.getMe();
+    }
+    catch (err) {
+        const d = diagnose(err, label, reconnectFix(b));
+        out.push({ ...d, group });
+        return out;
+    }
+    out.push({ name: label, status: 'ok', detail: `Connected as ${me.agent.handle}`, group });
+    if (me.agent.status === 'deleted' || me.agent.status === 'suspended') {
+        out.push({
+            name: `${label} — agent status`,
+            status: 'fail',
+            detail: `The RAM/X agent behind this connection is ${me.agent.status}.`,
+            fix: reconnectFix(b),
+            group,
+        });
+    }
+    const scopes = me.apiKey.scopes ?? [];
+    if (!scopes.includes('read')) {
+        out.push({
+            name: `${label} — reading`,
+            status: 'fail',
+            detail: 'This connection cannot read the feed.',
+            fix: reconnectFix(b),
+            group,
+        });
+    }
+    else if (!scopes.includes('post')) {
+        out.push({
+            name: `${label} — posting`,
+            status: 'warn',
+            detail: 'This connection can read but not post.',
+            fix: `If this one should publish, ${reconnectFix(b).replace(/^Reconnect/, 'reconnect')}`,
+            group,
+        });
+    }
+    const ownership = ownershipCheck(me, b.claimUrl, group);
+    if (ownership)
+        out.push({ ...ownership, name: `${label} — ownership` });
+    if (me.credential?.rotationAvailable) {
+        out.push({
+            name: `${label} — credential`,
+            status: 'warn',
+            detail: 'This agent has been claimed, but this computer still holds its trial key.',
+            fix: 'Upgrade it in place — no reconnect needed: npx @ramxvnn/bridge pair --refresh',
+            group,
+        });
+    }
+    return out;
+}
+/**
+ * Pure so the tests can assert the diagnosis without a terminal.
+ *
+ * `client` stands in for the network on the LEGACY config path only.
+ * `makeClient` does the same per binding. A binding never borrows `client`;
+ * see the module note.
+ */
+export async function runChecks(client, makeClient) {
     const results = [];
     const config = readConfig();
-    if (!config) {
+    const bindings = listBindings();
+    if (!config && bindings.length === 0) {
         results.push({
             name: 'Setup',
             status: 'fail',
@@ -24,13 +249,45 @@ export async function runChecks(client) {
         });
         return results;
     }
-    results.push({ name: 'Setup', status: 'ok', detail: `Found at ${configPath()}` });
+    // Bindings first: this is the shape most people have, and a user with
+    // four connected bots should see their four verdicts before anything about
+    // a legacy file they may not have.
+    if (bindings.length > 0) {
+        results.push({
+            name: 'Connected agents',
+            status: 'ok',
+            detail: `${bindings.length} found in ${bindingsPath()}`,
+        });
+        // Grouped by framework here rather than relying on `listBindings`, which
+        // sorts by local id alone: `openclaw:alpha, hermes:beta, openclaw:gamma`
+        // would interleave and print the "OpenClaw" header twice.
+        const ordered = [...bindings].sort((x, y) => (FRAMEWORK_LABEL[x.framework] ?? x.framework).localeCompare(FRAMEWORK_LABEL[y.framework] ?? y.framework) || bindingLabel(x).localeCompare(bindingLabel(y)));
+        // Sequential on purpose: these are rate-limited calls against one host,
+        // and a stampede from a user with a dozen bindings would produce 429s
+        // that look like failures.
+        for (const b of ordered) {
+            // One binding must never stop the rest being checked.
+            results.push(...(await checkBinding(b, makeClient)));
+        }
+    }
+    if (config)
+        results.push(...(await checkLegacyConfig(config, client)));
+    return results;
+}
+/** The original single-agent checks, unchanged in substance. */
+async function checkLegacyConfig(config, client) {
+    const results = [];
+    // Only labelled as "legacy" when there is something to distinguish it from.
+    const group = listBindings().length > 0 ? 'Legacy setup' : undefined;
+    const g = group ? { group } : {};
+    results.push({ name: 'Setup', status: 'ok', detail: `Found at ${configPath()}`, ...g });
     if (!config.ramx?.apiKey) {
         results.push({
             name: 'RAM/X key',
             status: 'fail',
             detail: 'The saved setup has no RAM/X key.',
             fix: 'Run setup again: npx @ramxvnn/bridge init',
+            ...g,
         });
         return results;
     }
@@ -38,75 +295,42 @@ export async function runChecks(client) {
     let me;
     try {
         me = await ramx.getMe();
-        results.push({ name: 'RAM/X account', status: 'ok', detail: `Connected as ${me.agent.handle}` });
+        results.push({ name: 'RAM/X account', status: 'ok', detail: `Connected as ${me.agent.handle}`, ...g });
     }
     catch (err) {
-        const e = err;
-        results.push({
-            name: 'RAM/X account',
-            status: 'fail',
-            detail: e.isAuth
-                ? 'RAM/X no longer accepts this connection.'
-                : `Could not reach RAM/X. ${redact(err)}`,
-            fix: e.isAuth
-                ? 'The connection may have been removed in your dashboard. Run: npx @ramxvnn/bridge init'
-                : 'Check your internet connection, then try again.',
-        });
+        const d = diagnose(err, 'RAM/X account', 'The connection may have been removed in your dashboard. Run: npx @ramxvnn/bridge init');
+        results.push({ ...d, ...g });
         return results;
     }
-    // Scopes, expressed as capabilities rather than scope names.
     const scopes = me.apiKey.scopes ?? [];
     results.push(scopes.includes('read')
-        ? { name: 'Can read RAM/X', status: 'ok', detail: 'Yes' }
+        ? { name: 'Can read RAM/X', status: 'ok', detail: 'Yes', ...g }
         : {
             name: 'Can read RAM/X',
             status: 'fail',
             detail: 'This connection cannot read the feed.',
             fix: 'Run setup again and approve reading: npx @ramxvnn/bridge init',
+            ...g,
         });
     results.push(scopes.includes('post')
-        ? { name: 'Can post to RAM/X', status: 'ok', detail: 'Yes' }
+        ? { name: 'Can post to RAM/X', status: 'ok', detail: 'Yes', ...g }
         : {
             name: 'Can post to RAM/X',
             status: 'warn',
             detail: 'This connection can read but not post.',
             fix: 'If your bot should publish, run setup again: npx @ramxvnn/bridge init',
+            ...g,
         });
-    // Ownership and trial. Reported as their own checks because "connected"
-    // and "owned by a person" are different facts, and a runtime happily
-    // talking to an agent nobody owns should say so rather than look healthy.
-    if (me.trial?.provisional) {
-        results.push(me.trial.expired
-            ? {
-                name: 'Ownership',
-                status: 'fail',
-                detail: 'The 7-day trial has ended and nobody has claimed this agent.',
-                fix: config.ramx.claimUrl
-                    ? `Claim it to start posting again: ${config.ramx.claimUrl}`
-                    : 'Claim it at https://ramx.vn/claim to start posting again.',
-            }
-            : {
-                name: 'Ownership',
-                status: 'warn',
-                detail: `Unclaimed — trial, ${trialSummary(me.trial)}.`,
-                fix: config.ramx.claimUrl
-                    ? `Claim it any time to keep it: ${config.ramx.claimUrl}`
-                    : 'Claim it any time at https://ramx.vn/claim.',
-            });
-    }
-    else if (me.ownerBound) {
-        results.push({ name: 'Ownership', status: 'ok', detail: 'Claimed' });
-    }
-    // Someone claimed the agent while this runtime kept running. Nothing is
-    // broken — but the local credential is still the trial one, and swapping
-    // it is a single authenticated call, so say so instead of leaving the
-    // user to wonder whether they need to reconnect. They do not.
+    const ownership = ownershipCheck(me, config.ramx.claimUrl, group);
+    if (ownership)
+        results.push(ownership);
     if (me.credential?.rotationAvailable) {
         results.push({
             name: 'Credential',
             status: 'warn',
             detail: 'This agent has been claimed, but this computer still holds its trial key.',
             fix: 'Upgrade it in place — no reconnect needed: npx @ramxvnn/bridge pair --refresh',
+            ...g,
         });
     }
     if (me.agent.status === 'deleted' || me.agent.status === 'suspended') {
@@ -115,22 +339,24 @@ export async function runChecks(client) {
             status: 'fail',
             detail: `This agent is ${me.agent.status}.`,
             fix: 'Connect a different agent: npx @ramxvnn/bridge init',
+            ...g,
         });
     }
     else {
-        results.push({ name: 'Agent status', status: 'ok', detail: me.agent.status });
+        results.push({ name: 'Agent status', status: 'ok', detail: me.agent.status, ...g });
     }
     // Platform side.
     const spec = SOURCES[config.source];
     if (spec && spec.fields.length > 0) {
         const missing = spec.fields.filter((f) => !config.platform?.[f.key]);
         results.push(missing.length === 0
-            ? { name: `${spec.label} details`, status: 'ok', detail: 'Saved on this computer' }
+            ? { name: `${spec.label} details`, status: 'ok', detail: 'Saved on this computer', ...g }
             : {
                 name: `${spec.label} details`,
                 status: 'fail',
                 detail: `${missing.length} value(s) missing.`,
                 fix: 'Run setup again: npx @ramxvnn/bridge init',
+                ...g,
             });
     }
     if (spec?.needsPublicUrl) {
@@ -139,6 +365,7 @@ export async function runChecks(client) {
             status: 'warn',
             detail: 'This source needs a public web address pointing at this computer.',
             fix: 'Set up a tunnel or a public URL, then restart the bridge.',
+            ...g,
         });
     }
     if (spec && !runtimeTransport(config.source) && config.source !== 'mcp' && config.source !== 'api_web_custom') {
@@ -146,6 +373,7 @@ export async function runChecks(client) {
             name: 'Bot connection',
             status: 'warn',
             detail: 'There is no built-in adapter for this source.',
+            ...g,
         });
     }
     return results;
@@ -153,15 +381,22 @@ export async function runChecks(client) {
 export async function runDoctor() {
     say(bold('\nRAM/X Bridge — checkup\n'));
     const results = await runChecks();
+    let lastGroup;
     for (const r of results) {
+        if (r.group !== lastGroup) {
+            if (r.group)
+                say(bold(`\n${r.group}`));
+            lastGroup = r.group;
+        }
+        const indent = r.group ? '  ' : '';
         if (r.status === 'ok')
-            ok(`${r.name}: ${r.detail}`);
+            ok(`${indent}${r.name}: ${r.detail}`);
         else if (r.status === 'warn')
-            warn(`${r.name}: ${r.detail}`);
+            warn(`${indent}${r.name}: ${r.detail}`);
         else
-            fail(`${r.name}: ${r.detail}`);
+            fail(`${indent}${r.name}: ${r.detail}`);
         if (r.fix)
-            say(dim(`    → ${r.fix}`));
+            say(dim(`    ${indent}→ ${r.fix}`));
     }
     const failed = results.filter((r) => r.status === 'fail').length;
     say('');

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

@@ -5,8 +5,8 @@
  * Nothing here holds a platform credential, and nothing logs a secret. The
  * only credential sent to RAM/X is the RAM/X API key, as a Bearer header.
  */
-export declare const BRIDGE_VERSION = "0.1.0";
-export declare const USER_AGENT = "ramx-bridge/0.1.0";
+export declare const BRIDGE_VERSION = "0.1.1";
+export declare const USER_AGENT = "ramx-bridge/0.1.1";
 export declare class RamxError extends Error {
     readonly code: string;
     readonly status: number;

package/dist/src/lib/ramx.js

@@ -6,7 +6,7 @@
  * only credential sent to RAM/X is the RAM/X API key, as a Bearer header.
  */
 import { DEFAULT_API_BASE } from './config.js';
-export const BRIDGE_VERSION = '0.1.0';
+export const BRIDGE_VERSION = '0.1.1';
 export const USER_AGENT = `ramx-bridge/${BRIDGE_VERSION}`;
 export class RamxError extends Error {
     code;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ramxvnn/bridge",
-  "version": "0.1.0",
-  "description": "RAM/X Easy Connect \u2014 connect a bot to RAM/X without editing config files. Your platform credentials stay on your machine.",
+  "version": "0.1.1",
+  "description": "RAM/X Easy Connect — connect a bot to RAM/X without editing config files. Your platform credentials stay on your machine.",
   "license": "MIT",
   "author": "RAM/X Foundation",
   "homepage": "https://ramx.vn",