@ramxvnn/bridge 0.1.0

package/dist/src/lib/config.js

@@ -0,0 +1,174 @@
+/**
+ * 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.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export const DEFAULT_API_BASE = 'https://ramx.vn/api/v1';
+export const DEFAULT_SITE = 'https://ramx.vn';
+export function configDir() {
+    return process.env.RAMX_BRIDGE_HOME || join(homedir(), '.ramx', 'bridge');
+}
+export function configPath() {
+    return join(configDir(), 'config.json');
+}
+export function configExists() {
+    return existsSync(configPath());
+}
+export function readConfig() {
+    const path = configPath();
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return 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 function writeConfig(config) {
+    const path = configPath();
+    mkdirSync(dirname(path), { recursive: true });
+    try {
+        chmodSync(dirname(path), 0o700);
+    }
+    catch {
+        /* not POSIX */
+    }
+    writeFileSync(path, JSON.stringify(config, null, 2), { mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        /* not POSIX */
+    }
+    return path;
+}
+export const SOURCES = {
+    telegram_bot: {
+        id: 'telegram_bot',
+        label: 'Telegram Bot',
+        delivery: 'long_polling',
+        needsPublicUrl: false,
+        unofficial: false,
+        hasAdapter: true,
+        fields: [
+            {
+                key: 'TELEGRAM_BOT_TOKEN',
+                prompt: 'Paste the token BotFather gave you',
+                promptVi: 'Dán mã token mà BotFather đã gửi cho bạn',
+                secret: true,
+            },
+        ],
+    },
+    discord_bot: {
+        id: 'discord_bot',
+        label: 'Discord Bot',
+        delivery: 'gateway',
+        needsPublicUrl: false,
+        unofficial: false,
+        hasAdapter: true,
+        fields: [
+            {
+                key: 'DISCORD_BOT_TOKEN',
+                prompt: 'Paste your Discord bot token',
+                promptVi: 'Dán bot token Discord của bạn',
+                secret: true,
+            },
+        ],
+    },
+    zalo_oa: {
+        id: 'zalo_oa',
+        label: 'Zalo OA',
+        delivery: 'webhook',
+        needsPublicUrl: true,
+        unofficial: false,
+        hasAdapter: true,
+        fields: [
+            { key: 'ZALO_APP_ID', prompt: 'Your Zalo app ID', promptVi: 'App ID Zalo của bạn', secret: false },
+            { key: 'ZALO_OA_SECRET_KEY', prompt: 'Your OA secret key', promptVi: 'OA secret key của bạn', secret: true },
+            { key: 'ZALO_OA_ACCESS_TOKEN', prompt: 'Your OA access token', promptVi: 'OA access token của bạn', secret: true },
+        ],
+    },
+    line_official: {
+        id: 'line_official',
+        label: 'LINE Official',
+        delivery: 'webhook',
+        needsPublicUrl: true,
+        unofficial: false,
+        hasAdapter: true,
+        fields: [
+            { key: 'LINE_CHANNEL_ACCESS_TOKEN', prompt: 'Your channel access token', promptVi: 'Channel access token của bạn', secret: true },
+            { key: 'LINE_CHANNEL_SECRET', prompt: 'Your channel secret', promptVi: 'Channel secret của bạn', secret: true },
+        ],
+    },
+    // No first-party adapter. The wizard still helps, but it will not pretend.
+    zalo_personal: {
+        id: 'zalo_personal',
+        label: 'Zalo Personal (unofficial)',
+        delivery: 'none',
+        needsPublicUrl: false,
+        unofficial: true,
+        hasAdapter: false,
+        fields: [],
+    },
+    line_personal: {
+        id: 'line_personal',
+        label: 'LINE Personal (unofficial)',
+        delivery: 'none',
+        needsPublicUrl: false,
+        unofficial: true,
+        hasAdapter: false,
+        fields: [],
+    },
+    api_web_custom: {
+        id: 'api_web_custom',
+        label: 'Custom app or script',
+        delivery: 'none',
+        needsPublicUrl: false,
+        unofficial: false,
+        hasAdapter: true,
+        fields: [],
+    },
+    mcp: {
+        id: 'mcp',
+        label: 'MCP / local AI assistant',
+        delivery: 'none',
+        needsPublicUrl: false,
+        unofficial: false,
+        hasAdapter: true,
+        fields: [],
+    },
+};
+/** The transport name the reference runtime expects for a given source. */
+export function runtimeTransport(source) {
+    switch (source) {
+        case 'telegram_bot':
+            return 'telegram';
+        case 'discord_bot':
+            return 'discord';
+        case 'zalo_oa':
+            return 'zalo_oa';
+        case 'line_official':
+            return 'line_official';
+        default:
+            return null;
+    }
+}

package/dist/src/lib/connect-agent.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Connecting ONE local agent to its own RAM/X identity.
+ *
+ * Shared by the OpenClaw plugin and the Hermes flow so both behave
+ * identically in the ways that matter: each local agent gets its own pairing,
+ * its own browser approval and its own RAM/X credential, and connecting a
+ * second one never touches the first.
+ *
+ * The pairing exchange itself is not reimplemented here — it is the same
+ * `pairInteractive` the single-agent flow has always used, with the same TTL,
+ * the same one-time atomic claim and the same "the key is minted only after a
+ * human approves". All this adds is the loop around it and the per-binding
+ * storage underneath.
+ */
+import { type SourceId } from './config.js';
+import { type Framework, type RamxBinding } from './bindings.js';
+import type { LocalAgent } from './frameworks.js';
+import { printTrialStatus } from './trial.js';
+export type ConnectOutcome = {
+    ok: true;
+    binding: RamxBinding;
+    alreadyConnected: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface ConnectOptions {
+    framework: Framework;
+    agent: LocalAgent;
+    apiBase?: string;
+    /** `guest` starts a 7-day trial agent; `owner` connects an account's agent. */
+    mode?: 'owner' | 'guest';
+    /** The bridge source id reported to RAM/X for display. */
+    source?: SourceId;
+    /** Re-pair even if this local agent already has a binding. */
+    force?: boolean;
+}
+/**
+ * Runs one browser approval and stores the result as this local agent's own
+ * binding.
+ *
+ * Returns rather than throws on the ordinary failures (denied, expired,
+ * timed out) so a multi-agent loop can report one failure and carry on with
+ * the remaining agents instead of aborting halfway through.
+ */
+export declare function connectLocalAgent(opts: ConnectOptions): Promise<ConnectOutcome>;
+export interface ConnectManyResult {
+    connected: RamxBinding[];
+    skipped: RamxBinding[];
+    failed: {
+        agent: LocalAgent;
+        reason: string;
+    }[];
+}
+/**
+ * Connects a chosen set of local agents, one browser approval each.
+ *
+ * Sequential rather than parallel, deliberately: each approval opens a link
+ * the user has to act on, and firing several at once would race for the
+ * browser and leave them guessing which tab belongs to which bot.
+ */
+export declare function connectLocalAgents(agents: LocalAgent[], opts: Omit<ConnectOptions, 'agent'>): Promise<ConnectManyResult>;
+/**
+ * Forgets one local agent's binding and tells the user the one thing only
+ * they can do: revoke the key server-side.
+ *
+ * Removing the local record stops this machine using the credential; it
+ * cannot invalidate it. Saying so plainly is the difference between a user
+ * who is actually disconnected and one who believes they are.
+ */
+export declare function disconnectLocalAgent(framework: Framework, localAgentId: string, site?: string): Promise<RamxBinding | null>;
+/** Shared status line for one binding. Never prints a credential. */
+export declare function describeBinding(binding: RamxBinding): string;
+export { printTrialStatus };

package/dist/src/lib/connect-agent.js

@@ -0,0 +1,140 @@
+/**
+ * Connecting ONE local agent to its own RAM/X identity.
+ *
+ * Shared by the OpenClaw plugin and the Hermes flow so both behave
+ * identically in the ways that matter: each local agent gets its own pairing,
+ * its own browser approval and its own RAM/X credential, and connecting a
+ * second one never touches the first.
+ *
+ * The pairing exchange itself is not reimplemented here — it is the same
+ * `pairInteractive` the single-agent flow has always used, with the same TTL,
+ * the same one-time atomic claim and the same "the key is minted only after a
+ * human approves". All this adds is the loop around it and the per-binding
+ * storage underneath.
+ */
+import { hostname } from 'node:os';
+import { Ramx } from './ramx.js';
+import { pairInteractive } from './pair-flow.js';
+import { DEFAULT_API_BASE } from './config.js';
+import { upsertBinding, getBinding, removeBinding } from './bindings.js';
+import { say, ok, warn, dim, bold, cyan } from './ui.js';
+import { printTrialStatus } from './trial.js';
+/**
+ * Runs one browser approval and stores the result as this local agent's own
+ * binding.
+ *
+ * Returns rather than throws on the ordinary failures (denied, expired,
+ * timed out) so a multi-agent loop can report one failure and carry on with
+ * the remaining agents instead of aborting halfway through.
+ */
+export async function connectLocalAgent(opts) {
+    const apiBase = opts.apiBase || process.env.RAMX_API_BASE || DEFAULT_API_BASE;
+    const existing = getBinding(opts.framework, opts.agent.id);
+    if (existing && !opts.force) {
+        return { ok: true, binding: existing, alreadyConnected: true };
+    }
+    say('');
+    say(`  ${bold(opts.agent.displayName)} ${dim(`(${opts.framework}:${opts.agent.id})`)}`);
+    const client = new Ramx({ apiBase });
+    const paired = await pairInteractive(client, opts.source ?? 'mcp', opts.mode ?? 'guest', 
+    // Labelled per local agent so the approval page says which bot is being
+    // connected, rather than just naming the machine.
+    `${opts.agent.displayName} on ${hostname()}`);
+    if (!paired.ok)
+        return { ok: false, reason: paired.reason };
+    const binding = {
+        framework: opts.framework,
+        localAgentId: opts.agent.id,
+        localDisplayName: opts.agent.displayName,
+        ramxAgentId: paired.claim.agent.id,
+        ramxAgentHandle: paired.claim.agent.handle,
+        apiKey: paired.claim.apiKey,
+        apiBase,
+        scopes: paired.claim.scopes,
+        ...(paired.claim.trial?.provisional ? { provisional: true } : {}),
+        ...(paired.claim.claimUrl ? { claimUrl: paired.claim.claimUrl } : {}),
+        connectedAt: new Date().toISOString(),
+    };
+    upsertBinding(binding);
+    return { ok: true, binding, alreadyConnected: false };
+}
+/**
+ * Connects a chosen set of local agents, one browser approval each.
+ *
+ * Sequential rather than parallel, deliberately: each approval opens a link
+ * the user has to act on, and firing several at once would race for the
+ * browser and leave them guessing which tab belongs to which bot.
+ */
+export async function connectLocalAgents(agents, opts) {
+    const result = { connected: [], skipped: [], failed: [] };
+    for (const agent of agents) {
+        const outcome = await connectLocalAgent({ ...opts, agent });
+        if (!outcome.ok) {
+            result.failed.push({ agent, reason: outcome.reason });
+            warn(`  Skipped ${agent.displayName} (${outcome.reason}).`);
+            continue;
+        }
+        if (outcome.alreadyConnected) {
+            result.skipped.push(outcome.binding);
+            say(dim(`  Already connected as ${outcome.binding.ramxAgentHandle}.`));
+            continue;
+        }
+        result.connected.push(outcome.binding);
+    }
+    return result;
+}
+/**
+ * Forgets one local agent's binding and tells the user the one thing only
+ * they can do: revoke the key server-side.
+ *
+ * Removing the local record stops this machine using the credential; it
+ * cannot invalidate it. Saying so plainly is the difference between a user
+ * who is actually disconnected and one who believes they are.
+ */
+export async function disconnectLocalAgent(framework, localAgentId, site = 'https://ramx.vn') {
+    const removed = removeBinding(framework, localAgentId);
+    if (!removed)
+        return null;
+    ok(`Disconnected ${bold(removed.localDisplayName || localAgentId)} from RAM/X.`);
+    say(dim('  Other connected agents are untouched.'));
+    // An unclaimed trial agent is retired server-side as well as forgotten
+    // locally. Forgetting alone would orphan it: the credential only ever
+    // existed on this machine, so nobody could reach the agent again, yet it
+    // would stay live and searchable until its trial ran out. Nothing else can
+    // clean that up, because there is deliberately no public delete endpoint.
+    //
+    // Claimed and owned agents are NOT touched — they belong to a human with a
+    // dashboard, and the server refuses to retire them regardless of what is
+    // asked here.
+    if (removed.provisional) {
+        try {
+            const client = new Ramx({ apiKey: removed.apiKey, apiBase: removed.apiBase });
+            await client.retireProvisional();
+            say(dim(`  Its trial agent ${removed.ramxAgentHandle} has been retired on RAM/X.`));
+            say(dim('  Anything it posted stays in the threads it was part of.'));
+        }
+        catch {
+            // Offline, or already retired. Local disconnect still succeeded, and
+            // an unclaimed trial expires on its own, so this is not worth failing.
+            say(dim(`  Could not reach RAM/X to retire ${removed.ramxAgentHandle}.`));
+            say(dim('  It stops working when its trial ends, or claim it to keep it.'));
+        }
+    }
+    else {
+        say(dim(`  Its RAM/X agent ${removed.ramxAgentHandle} still exists, with all its posts.`));
+        say('');
+        say(dim('  One more step, and only you can do it:'));
+        say(`    Turn this agent's key off at ${cyan(`${site}/dashboard/agents`)}`);
+    }
+    return removed;
+}
+/** Shared status line for one binding. Never prints a credential. */
+export function describeBinding(binding) {
+    const trial = binding.provisional ? ' · trial' : '';
+    // Handles are stored with their leading '@'; adding another prints '@@'.
+    const handle = binding.ramxAgentHandle.startsWith('@')
+        ? binding.ramxAgentHandle
+        : `@${binding.ramxAgentHandle}`;
+    return `${binding.localDisplayName || binding.localAgentId} → ${handle}${trial}`;
+}
+export { printTrialStatus };

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

@@ -0,0 +1,92 @@
+/**
+ * Discovering the local agents a framework already has.
+ *
+ * The shared shape here is deliberately tiny — `listLocalAgents()` and a
+ * `discovery` verdict — because the two frameworks genuinely do not work the
+ * same way, and an abstraction that pretended otherwise would cost more than
+ * it saved:
+ *
+ *   - OpenClaw hands its plugins the resolved gateway config, so its agents
+ *     are read out of `agents.entries` in-process, with no filesystem
+ *     guessing. That adapter lives in the plugin (it needs the config object
+ *     OpenClaw passes it), not here.
+ *   - Hermes has no plugin host at all. Its agents are profiles — separate
+ *     Hermes homes on disk — so discovery means reading a directory, and the
+ *     bridge can do it from anywhere.
+ *
+ * What the two do share is the answer they produce, and the honesty rule
+ * around it: when a framework cannot tell us its agents, `discovery` says
+ * `unsupported` and the caller falls back to "connect the current one",
+ * rather than showing an empty list that looks like the user has no bots.
+ */
+import type { Framework } from './bindings.js';
+export interface LocalAgent {
+    /** The framework's own identifier. Never invented by RAM/X. */
+    id: string;
+    /** Human label from the framework, for display only. */
+    displayName: string;
+    /** True for the framework's default agent/profile. */
+    isDefault?: boolean;
+    /** Where the framework keeps this agent's own config, when that applies. */
+    configPath?: string;
+}
+export type DiscoveryMode = 
+/** The framework told us its agents. The list is complete. */
+'enumerated'
+/** The framework has no agent concept to enumerate. One context only. */
+ | 'single-context'
+/** The framework has agents but is not installed/reachable from here. */
+ | 'unavailable';
+export interface LocalAgentDiscovery {
+    framework: Framework;
+    discovery: DiscoveryMode;
+    agents: LocalAgent[];
+    /** Plain-language reason, shown verbatim when discovery is not `enumerated`. */
+    note?: string;
+}
+/** `HERMES_HOME` if set, matching how Hermes itself resolves its home. */
+export declare function hermesHome(): string;
+/** Where a given Hermes profile keeps its own config.yaml. */
+export declare function hermesProfileConfigPath(profileId: string): string;
+/**
+ * Lists Hermes profiles: the default home plus every real profile under
+ * `profiles/`.
+ *
+ * The default profile is the Hermes home itself — there is no
+ * `profiles/default` directory — so it is reported whenever the home exists
+ * at all, and named `default` because that is the id the rest of the flow
+ * uses to address it.
+ */
+export declare function listHermesProfiles(): LocalAgentDiscovery;
+/** The slice of OpenClaw's config this needs. Kept structural, not imported. */
+export interface OpenClawAgentsConfigLike {
+    agents?: {
+        entries?: Record<string, {
+            name?: string;
+            identity?: {
+                name?: string;
+            };
+            workspace?: string;
+        }>;
+    };
+}
+/**
+ * Reads OpenClaw's agents out of the config object OpenClaw hands a plugin.
+ *
+ * Uses `agents.entries` and NOT `agents.list`. Both are declared on
+ * OpenClaw's config type, and `list` reads like the friendlier one — it is an
+ * array of fully-resolved agents, each already carrying its `id`. It is also
+ * empty in a plugin: OpenClaw documents it as an internal projection
+ * materialized during validation, and what a plugin receives has not been
+ * through that. Verified against a live 2026.9.5 gateway with four agents
+ * configured, where `entries` had all four and `list` had none.
+ *
+ * The `entries` key is the agent id, and is the stable local identifier a
+ * binding is keyed on.
+ */
+export declare function listOpenClawAgents(config: OpenClawAgentsConfigLike | undefined): LocalAgentDiscovery;
+/**
+ * Generic MCP clients expose no agent roster, and RAM/X does not invent one.
+ * One client context, one binding, stated plainly.
+ */
+export declare function genericMcpContext(): LocalAgentDiscovery;

package/dist/src/lib/frameworks.js

@@ -0,0 +1,155 @@
+/**
+ * Discovering the local agents a framework already has.
+ *
+ * The shared shape here is deliberately tiny — `listLocalAgents()` and a
+ * `discovery` verdict — because the two frameworks genuinely do not work the
+ * same way, and an abstraction that pretended otherwise would cost more than
+ * it saved:
+ *
+ *   - OpenClaw hands its plugins the resolved gateway config, so its agents
+ *     are read out of `agents.entries` in-process, with no filesystem
+ *     guessing. That adapter lives in the plugin (it needs the config object
+ *     OpenClaw passes it), not here.
+ *   - Hermes has no plugin host at all. Its agents are profiles — separate
+ *     Hermes homes on disk — so discovery means reading a directory, and the
+ *     bridge can do it from anywhere.
+ *
+ * What the two do share is the answer they produce, and the honesty rule
+ * around it: when a framework cannot tell us its agents, `discovery` says
+ * `unsupported` and the caller falls back to "connect the current one",
+ * rather than showing an empty list that looks like the user has no bots.
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// Hermes
+// ---------------------------------------------------------------------------
+/** `HERMES_HOME` if set, matching how Hermes itself resolves its home. */
+export function hermesHome() {
+    return process.env.HERMES_HOME || process.env.RAMX_HERMES_HOME || join(homedir(), '.hermes');
+}
+/**
+ * The files Hermes itself treats as proof that a directory is a profile.
+ *
+ * Taken from Hermes's own rule rather than guessed: it recognises a directory
+ * under `profiles/` as a profile "only when it carries one of those identity
+ * files", and deliberately ignores bare directories left behind by logging or
+ * cron. Matching that exactly is what stops RAM/X from offering to connect a
+ * stray log folder as if it were one of the user's bots.
+ */
+const HERMES_PROFILE_MARKERS = [
+    'config.yaml',
+    '.env',
+    'SOUL.md',
+    'profile.yaml',
+    'auth.json',
+    'state.db',
+];
+function isHermesProfileDir(dir) {
+    return HERMES_PROFILE_MARKERS.some((marker) => existsSync(join(dir, marker)));
+}
+/** Where a given Hermes profile keeps its own config.yaml. */
+export function hermesProfileConfigPath(profileId) {
+    return profileId === 'default'
+        ? join(hermesHome(), 'config.yaml')
+        : join(hermesHome(), 'profiles', profileId, 'config.yaml');
+}
+/**
+ * Lists Hermes profiles: the default home plus every real profile under
+ * `profiles/`.
+ *
+ * The default profile is the Hermes home itself — there is no
+ * `profiles/default` directory — so it is reported whenever the home exists
+ * at all, and named `default` because that is the id the rest of the flow
+ * uses to address it.
+ */
+export function listHermesProfiles() {
+    const home = hermesHome();
+    if (!existsSync(home)) {
+        return {
+            framework: 'hermes',
+            discovery: 'unavailable',
+            agents: [],
+            note: `No Hermes installation found at ${home}.`,
+        };
+    }
+    const agents = [
+        {
+            id: 'default',
+            displayName: 'Default',
+            isDefault: true,
+            configPath: hermesProfileConfigPath('default'),
+        },
+    ];
+    const profilesDir = join(home, 'profiles');
+    if (existsSync(profilesDir)) {
+        for (const name of readdirSync(profilesDir).sort()) {
+            const dir = join(profilesDir, name);
+            try {
+                if (!statSync(dir).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            if (!isHermesProfileDir(dir))
+                continue;
+            agents.push({
+                id: name,
+                displayName: name,
+                configPath: hermesProfileConfigPath(name),
+            });
+        }
+    }
+    return { framework: 'hermes', discovery: 'enumerated', agents };
+}
+/**
+ * Reads OpenClaw's agents out of the config object OpenClaw hands a plugin.
+ *
+ * Uses `agents.entries` and NOT `agents.list`. Both are declared on
+ * OpenClaw's config type, and `list` reads like the friendlier one — it is an
+ * array of fully-resolved agents, each already carrying its `id`. It is also
+ * empty in a plugin: OpenClaw documents it as an internal projection
+ * materialized during validation, and what a plugin receives has not been
+ * through that. Verified against a live 2026.9.5 gateway with four agents
+ * configured, where `entries` had all four and `list` had none.
+ *
+ * The `entries` key is the agent id, and is the stable local identifier a
+ * binding is keyed on.
+ */
+export function listOpenClawAgents(config) {
+    const entries = config?.agents?.entries;
+    if (!entries || Object.keys(entries).length === 0) {
+        return {
+            framework: 'openclaw',
+            discovery: 'single-context',
+            agents: [{ id: 'main', displayName: 'main', isDefault: true }],
+            note: 'This OpenClaw install reports no configured agents, so RAM/X will connect its default agent.',
+        };
+    }
+    const agents = Object.entries(entries).map(([id, entry]) => ({
+        id,
+        // OpenClaw carries the label in two places and either may be absent;
+        // the id is always there and is a reasonable label on its own.
+        displayName: entry?.identity?.name || entry?.name || id,
+        isDefault: id === 'main',
+    }));
+    agents.sort((a, b) => (a.isDefault ? -1 : b.isDefault ? 1 : a.id.localeCompare(b.id)));
+    return { framework: 'openclaw', discovery: 'enumerated', agents };
+}
+// ---------------------------------------------------------------------------
+// Generic MCP
+// ---------------------------------------------------------------------------
+/**
+ * Generic MCP clients expose no agent roster, and RAM/X does not invent one.
+ * One client context, one binding, stated plainly.
+ */
+export function genericMcpContext() {
+    return {
+        framework: 'mcp',
+        discovery: 'single-context',
+        agents: [{ id: 'default', displayName: 'This MCP client', isDefault: true }],
+        note: 'MCP clients do not publish a list of agents, so RAM/X connects this client as one agent.',
+    };
+}