@mcpbridgeapp/cli 0.0.0-stage → 0.1.0

package/dist/agents/registry.js

@@ -0,0 +1,167 @@
+import { BrokenAgent } from './broken.js';
+import { CliAgent } from './cli.js';
+import { OllamaAgent } from './ollama.js';
+import { OpenAiAgent } from './openai.js';
+import { HealthStore } from './health.js';
+import { classifyFailure, onlyAnnounced, selfReportedFailure } from './outcome.js';
+import { failed } from './types.js';
+export class AgentRegistry {
+    health;
+    agents = new Map();
+    /**
+     * The health store is passed in so it can outlive a registry: the control panel rebuilds
+     * the registry whenever the config changes, and what was learned must survive that.
+     */
+    misconfigured = new Map();
+    constructor(config, health = new HealthStore()) {
+        this.health = health;
+        for (const [name, agentConfig] of Object.entries(config.agents)) {
+            const agent = build(name.toLowerCase(), agentConfig, config.maxOutputChars);
+            if (agent instanceof BrokenAgent)
+                this.misconfigured.set(agent.name, agent.reason);
+            this.agents.set(name.toLowerCase(), tracked(agent, health));
+        }
+    }
+    /** Why an agent's configuration was rejected, or null if it was accepted. */
+    configError(name) {
+        return this.misconfigured.get(name.trim().toLowerCase()) ?? null;
+    }
+    find(name) {
+        return this.agents.get(name.trim().toLowerCase());
+    }
+    names() {
+        return [...this.agents.keys()].sort();
+    }
+    /** Probes every agent at once, since each probe is a filesystem or socket check. */
+    async statuses() {
+        const probed = await Promise.all([...this.agents.values()].map(async (agent) => {
+            const probe = await agent.probe();
+            const status = this.health.state(agent.name, probe.available);
+            const health = this.health.get(agent.name);
+            const failure = health?.lastFailure;
+            const remembered = status !== 'ready' && status !== 'unavailable' && failure
+                ? `${STATE_TEXT[status]} on the last call (${new Date(failure.at).toISOString()}): ${failure.message}${failure.retryAt ? ` -- it said to try again ${failure.retryAt}` : ''}`
+                : null;
+            const result = {
+                name: agent.name,
+                description: agent.description,
+                requires: agent.requires,
+                available: status === 'ready',
+                status,
+                readsFiles: agent.readsFiles,
+                writesFiles: agent.writesFiles,
+                runsCommands: agent.runsCommands,
+                timeoutSeconds: Math.round(agent.timeoutMs / 1000),
+                detail: remembered ?? probe.detail,
+                calls: health?.calls ?? 0,
+            };
+            if (failure) {
+                result.lastError = failure.message;
+                result.lastErrorAt = new Date(failure.at).toISOString();
+                if (failure.retryAt)
+                    result.retryAt = failure.retryAt;
+            }
+            if (health?.lastSuccessAt)
+                result.lastSuccessAt = new Date(health.lastSuccessAt).toISOString();
+            return result;
+        }));
+        return probed.sort((a, b) => a.name.localeCompare(b.name));
+    }
+}
+const STATE_TEXT = {
+    ready: 'ready',
+    unavailable: 'unavailable',
+    'quota-exhausted': 'usage limit reached',
+    'sign-in-failed': 'sign-in failed',
+    'directory-not-trusted': 'refused the working directory',
+};
+/**
+ * Every run goes through here, so whichever front door a call came in by, the result is
+ * read the same way: an agent that exited 0 but says it could not do the work is a
+ * failure, and every outcome is remembered for list_agents.
+ */
+function tracked(agent, health) {
+    return {
+        get name() { return agent.name; },
+        get description() { return agent.description; },
+        get requires() { return agent.requires; },
+        get readsFiles() { return agent.readsFiles; },
+        get writesFiles() { return agent.writesFiles; },
+        get runsCommands() { return agent.runsCommands; },
+        get timeoutMs() { return agent.timeoutMs; },
+        probe: () => agent.probe(),
+        run: async (prompt, options) => {
+            // a used-up quota or a failed sign-in fails the same way next time: four tasks
+            // started together on one exhausted account should cost one failure, not four
+            const known = health.get(agent.name)?.lastFailure;
+            const state = health.state(agent.name, true);
+            if (!options.force && known && state !== 'ready') {
+                return failed(agent.name, `not started: ${agent.name} hit "${STATE_TEXT[state]}" on a call at ${new Date(known.at).toISOString()} ` +
+                    `(${known.message})${known.retryAt ? `, and said to try again ${known.retryAt}` : ''}. ` +
+                    'Choose another agent; this one is tried again once that clears, or when its owner retests it.');
+            }
+            const result = await agent.run(prompt, options);
+            const judged = judge(agent, result);
+            health.record(agent.name, judged);
+            return judged;
+        },
+    };
+}
+function judge(agent, result) {
+    const name = agent.name;
+    if (result.succeeded) {
+        const admitted = selfReportedFailure(result.output);
+        if (admitted) {
+            return {
+                ...result,
+                succeeded: false,
+                diagnostics: `${name} exited normally, but its answer says it could not do the task: "${admitted}" ` +
+                    'Treat "output" as its explanation, not as a result.',
+            };
+        }
+        if (onlyAnnounced(result.output)) {
+            const limited = !agent.writesFiles || !agent.runsCommands;
+            return {
+                ...result,
+                succeeded: false,
+                diagnostics: `${name} exited normally, but its whole answer only says what it was about to do. ` +
+                    (limited
+                        ? 'It probably stopped at a step it was not allowed to take -- it is not allowed to ' +
+                            `${[!agent.writesFiles ? 'change files' : '', !agent.runsCommands ? 'run commands' : ''].filter(Boolean).join(' or ')} ` +
+                            'here. Ask it only to read and report, or have its owner allow that step for this agent.'
+                        : 'Ask again, or give it a smaller task.'),
+            };
+        }
+    }
+    if (classifyFailure(result.diagnostics).kind === 'trust') {
+        return {
+            ...result,
+            diagnostics: `${result.diagnostics}\n\nThis CLI refuses directories it has not been told to trust when it runs ` +
+                'unattended. mcpbridgeapp does not trust them on its behalf, because the directory is chosen by ' +
+                'whichever client made the call. If you trust the projects your clients send it to, set the ' +
+                'variable the CLI names under this agent\'s "env" in config.json, e.g. ' +
+                '"env": { "GEMINI_CLI_TRUST_WORKSPACE": "true" } for gemini.',
+        };
+    }
+    return result;
+}
+/**
+ * A rejected config becomes a BrokenAgent rather than an exception: one typo should cost
+ * that agent, not the whole bridge and every other agent with it.
+ */
+function build(name, config, maxOutputChars) {
+    try {
+        switch (config.type) {
+            case 'ollama':
+                return new OllamaAgent(name, config, maxOutputChars);
+            case 'openai':
+                return new OpenAiAgent(name, config, maxOutputChars);
+            default:
+                return new CliAgent(name, config, maxOutputChars);
+        }
+    }
+    catch (error) {
+        return new BrokenAgent(name, error.message);
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/agents/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/agents/registry.ts"],"names":[],"mappings":"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"}

package/dist/agents/shim.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What a Windows batch shim actually invokes.
+ *
+ * @param command  the executable to run instead of the shim
+ * @param prefix   arguments that must come before the agent's own, e.g. the script path
+ *                 when the shim runs a .js file through node
+ */
+export interface ShimTarget {
+    command: string;
+    prefix: string[];
+}
+/**
+ * Finds the real program behind an npm-generated .cmd shim.
+ *
+ * <p>Windows users get a shim for every npm-installed CLI, and a shim can only be run
+ * through a shell — which a prompt must never touch. Rather than refusing every such
+ * agent, which on Windows is all of them, the shim is read and the program it calls is
+ * run directly. The shim is only ever read, never executed.
+ *
+ * <p>npm writes the target as a quoted path built from %dp0%, the shim's own directory:
+ *
+ * <pre>
+ *   "%dp0%\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe"   %*
+ * </pre>
+ *
+ * and, for packages without a native binary, as a script passed to node:
+ *
+ * <pre>
+ *   "%_prog%"  "%dp0%\\node_modules\\some-cli\\cli.js" %*
+ * </pre>
+ *
+ * Both shapes are handled, and a target that is not on disk is ignored, so a shim this
+ * does not understand falls back to being refused rather than producing a wrong command.
+ */
+export declare function parseShimTarget(content: string, shimDir: string, nodeExecutable: string, exists?: (path: string) => boolean): ShimTarget | null;

package/dist/agents/shim.js

@@ -0,0 +1,53 @@
+import { existsSync } from 'node:fs';
+import { win32 as windowsPath } from 'node:path';
+const QUOTED_DP0 = /"([^"]*%dp0%[^"]*)"/gi;
+const RUNNABLE = /\.(exe|com|js|cjs|mjs)$/i;
+/**
+ * Finds the real program behind an npm-generated .cmd shim.
+ *
+ * <p>Windows users get a shim for every npm-installed CLI, and a shim can only be run
+ * through a shell — which a prompt must never touch. Rather than refusing every such
+ * agent, which on Windows is all of them, the shim is read and the program it calls is
+ * run directly. The shim is only ever read, never executed.
+ *
+ * <p>npm writes the target as a quoted path built from %dp0%, the shim's own directory:
+ *
+ * <pre>
+ *   "%dp0%\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe"   %*
+ * </pre>
+ *
+ * and, for packages without a native binary, as a script passed to node:
+ *
+ * <pre>
+ *   "%_prog%"  "%dp0%\\node_modules\\some-cli\\cli.js" %*
+ * </pre>
+ *
+ * Both shapes are handled, and a target that is not on disk is ignored, so a shim this
+ * does not understand falls back to being refused rather than producing a wrong command.
+ */
+export function parseShimTarget(content, shimDir, nodeExecutable, exists = existsSync) {
+    const candidates = [];
+    for (const match of content.matchAll(QUOTED_DP0)) {
+        const raw = match[1];
+        if (!raw)
+            continue;
+        // win32 semantics explicitly: a shim is a Windows file, and the default path module
+        // would read "C:\\..." as a relative path everywhere else — including in these tests
+        const substituted = raw.replace(/%dp0%/gi, `${shimDir}\\`).replace(/\\\\+/g, '\\');
+        const resolved = windowsPath.isAbsolute(substituted)
+            ? windowsPath.normalize(substituted)
+            : windowsPath.normalize(windowsPath.join(shimDir, substituted));
+        if (RUNNABLE.test(resolved) && exists(resolved))
+            candidates.push(resolved);
+    }
+    if (candidates.length === 0)
+        return null;
+    // a native binary is run as itself; a script needs the node that is running us, not the
+    // bare "node" the shim would have looked up on PATH
+    const binary = candidates.find((path) => /\.(exe|com)$/i.test(path));
+    if (binary)
+        return { command: binary, prefix: [] };
+    const script = candidates[0];
+    return { command: nodeExecutable, prefix: [script] };
+}
+//# sourceMappingURL=shim.js.map

package/dist/agents/shim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shim.js","sourceRoot":"","sources":["../../src/agents/shim.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AAcjD,MAAM,UAAU,GAAG,uBAAuB,CAAC;AAC3C,MAAM,QAAQ,GAAG,0BAA0B,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAe,EACf,OAAe,EACf,cAAsB,EACtB,SAAoC,UAAU;IAE9C,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACjD,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACrB,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,oFAAoF;QACpF,qFAAqF;QACrF,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACnF,MAAM,QAAQ,GAAG,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC;YAClD,CAAC,CAAC,WAAW,CAAC,SAAS,CAAC,WAAW,CAAC;YACpC,CAAC,CAAC,WAAW,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC;QAClE,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEzC,wFAAwF;IACxF,oDAAoD;IACpD,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACrE,IAAI,MAAM;QAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAEnD,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAE,CAAC;IAC9B,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;AACvD,CAAC"}

package/dist/agents/types.d.ts

@@ -0,0 +1,69 @@
+/** What a delegated task produced. Every agent kind returns this same shape. */
+export interface AgentResult {
+    agent: string;
+    succeeded: boolean;
+    /** what the agent produced — the answer */
+    output: string;
+    /** why it failed, empty when it did not */
+    diagnostics: string;
+    /**
+     * Something the caller should know about a call that still succeeded — for instance
+     * that a workingDirectory was ignored because this agent cannot read files. Kept apart
+     * from diagnostics so "succeeded with a caveat" is not mistaken for a failure.
+     */
+    notes: string;
+    durationMs: number;
+    timedOut: boolean;
+    outputTruncated: boolean;
+}
+export interface RunOptions {
+    /** directory to run in, so the agent can see a project's files */
+    cwd?: string;
+    /** the caller's own bound; only ever shortens the agent's configured timeout */
+    timeoutMs?: number;
+    /** told each piece of output as it arrives, so a running task can show progress */
+    onOutput?: (chunk: string) => void;
+    /** run even though an earlier call hit a durable failure; for an explicit retry */
+    force?: boolean;
+}
+/** The configured limit, lowered to the caller's when the caller asked for less. */
+export declare function effectiveTimeout(configured: number | undefined, options: RunOptions): number;
+/**
+ * One agent the bridge can hand work to. A CLI and a local model look identical from
+ * here, which is what lets a caller treat them interchangeably.
+ */
+export interface Agent {
+    readonly name: string;
+    readonly description: string;
+    /** the executable or endpoint that has to exist, reported by list_agents */
+    readonly requires: string;
+    /**
+     * Whether pointing this agent at a directory actually lets it read the files there. A
+     * coding CLI can; a model behind an HTTP API cannot, and the caller has to inline the
+     * context instead of assuming otherwise.
+     */
+    readonly readsFiles: boolean;
+    /** whether, as configured, it may create or change files in the working directory */
+    readonly writesFiles: boolean;
+    /** whether, as configured, it may run shell commands such as tests or builds */
+    readonly runsCommands: boolean;
+    /** the longest one call may run before it is stopped */
+    readonly timeoutMs: number;
+    /** whether it can actually be used right now */
+    probe(): Promise<{
+        available: boolean;
+        detail: string;
+    }>;
+    run(prompt: string, options: RunOptions): Promise<AgentResult>;
+}
+export declare function failed(agent: string, diagnostics: string, durationMs?: number, timedOut?: boolean): AgentResult;
+/**
+ * Strips terminal escape sequences. A CLI writing colour, spinners or progress bars to
+ * stdout would otherwise have all of it land in the calling model's context as if it were
+ * part of the answer.
+ */
+export declare function stripAnsi(text: string): string;
+export declare function truncate(text: string, maxChars: number): {
+    text: string;
+    truncated: boolean;
+};

package/dist/agents/types.js

@@ -0,0 +1,28 @@
+/** The configured limit, lowered to the caller's when the caller asked for less. */
+export function effectiveTimeout(configured, options) {
+    const base = configured ?? 300_000;
+    return options.timeoutMs && options.timeoutMs > 0 ? Math.min(base, options.timeoutMs) : base;
+}
+export function failed(agent, diagnostics, durationMs = 0, timedOut = false) {
+    return {
+        agent, succeeded: false, output: '', diagnostics, notes: '',
+        durationMs, timedOut, outputTruncated: false,
+    };
+}
+// eslint-disable-next-line no-control-regex
+const ANSI = /[\u001B\u009B][[\]()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-PR-TZcf-nq-uy=><~]/g;
+/**
+ * Strips terminal escape sequences. A CLI writing colour, spinners or progress bars to
+ * stdout would otherwise have all of it land in the calling model's context as if it were
+ * part of the answer.
+ */
+export function stripAnsi(text) {
+    return text.replace(ANSI, '');
+}
+export function truncate(text, maxChars) {
+    const trimmed = stripAnsi(text).trim();
+    if (trimmed.length <= maxChars)
+        return { text: trimmed, truncated: false };
+    return { text: `${trimmed.slice(0, maxChars)}\n...[truncated]`, truncated: true };
+}
+//# sourceMappingURL=types.js.map

package/dist/agents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AA8BA,oFAAoF;AACpF,MAAM,UAAU,gBAAgB,CAAC,UAA8B,EAAE,OAAmB;IAClF,MAAM,IAAI,GAAG,UAAU,IAAI,OAAO,CAAC;IACnC,OAAO,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/F,CAAC;AA4BD,MAAM,UAAU,MAAM,CAAC,KAAa,EAAE,WAAmB,EAAE,UAAU,GAAG,CAAC,EAAE,QAAQ,GAAG,KAAK;IACzF,OAAO;QACL,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE;QAC3D,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,KAAK;KAC7C,CAAC;AACJ,CAAC;AAED,4CAA4C;AAC5C,MAAM,IAAI,GAAG,mFAAmF,CAAC;AAEjG;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,QAAgB;IACrD,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACvC,IAAI,OAAO,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC3E,OAAO,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,kBAAkB,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AACpF,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,99 @@
+export interface CliAgentConfig {
+    type?: 'cli';
+    description?: string;
+    /** argv; needs one element containing {prompt} unless promptVia is "stdin" */
+    command: string[];
+    /**
+     * How the prompt reaches the agent. "argv" is subject to the operating system's
+     * argument-size limit, which a prompt carrying file contents passes easily — roughly
+     * 64KB on Linux and 32KB on Windows, after which the spawn fails outright. "stdin" has
+     * no such limit, and is right for any CLI that reads its prompt from a pipe.
+     */
+    promptVia?: 'argv' | 'stdin';
+    timeoutMs?: number;
+    /** default directory, overridden per call */
+    cwd?: string;
+    /** extra environment for the child, merged over this process's own */
+    env?: Record<string, string>;
+    /**
+     * What this agent may do unattended. Off by default: a client that can call the bridge
+     * should not be able to make an agent change files or run commands unless the owner
+     * chose that. For the CLIs the bridge knows (claude, codex, grok, gemini) these become
+     * that CLI's own flags.
+     */
+    allow?: {
+        edits?: boolean;
+        commands?: boolean;
+        trustDirectory?: boolean;
+    };
+    /** for a CLI the bridge does not know: what its configured command lets it do */
+    capabilities?: {
+        writesFiles?: boolean;
+        runsCommands?: boolean;
+    };
+}
+export interface OllamaAgentConfig {
+    type: 'ollama';
+    description?: string;
+    /** omit to use the first model Ollama reports as installed */
+    model?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+}
+/**
+ * A model behind an OpenAI-compatible /chat/completions endpoint. Almost every provider
+ * that is not Anthropic or Google exposes one, so this single shape reaches xAI (Grok),
+ * DeepSeek, Mistral, Groq, Together, OpenRouter, LM Studio, llama.cpp and vLLM — only the
+ * base URL, the model name and the key differ.
+ */
+export interface OpenAiAgentConfig {
+    type: 'openai';
+    description?: string;
+    /** e.g. https://api.x.ai/v1 — the part before /chat/completions */
+    baseUrl: string;
+    /**
+     * The provider's model id. Left out until you know it: with a key set, probing lists
+     * what the endpoint offers, where the provider exposes a listing.
+     */
+    model?: string;
+    /**
+     * Name of the environment variable holding the key — not the key itself. Config files
+     * get copied into repos and pasted into issues; an environment variable does not.
+     */
+    apiKeyEnv?: string;
+    /** The key inline. Works, but prefer apiKeyEnv: this file is easy to leak. */
+    apiKey?: string;
+    /** extra headers some providers want, e.g. OpenRouter's attribution headers */
+    headers?: Record<string, string>;
+    maxOutputTokens?: number;
+    timeoutMs?: number;
+}
+export type AgentConfig = CliAgentConfig | OllamaAgentConfig | OpenAiAgentConfig;
+export interface Config {
+    maxOutputChars: number;
+    /**
+     * How many delegations may run at once. Each one is a whole model doing real work, so
+     * an unbounded number of them saturates the machine and burns through the quota of
+     * whatever account is behind them.
+     */
+    maxConcurrent: number;
+    agents: Record<string, AgentConfig>;
+}
+/**
+ * Works with no configuration at all: the CLIs people already have, plus whatever Ollama
+ * is serving locally. An entry whose tool is not installed is simply reported as
+ * unavailable by list_agents, so shipping all four costs nothing.
+ *
+ * The flags are each tool's documented non-interactive mode, but they do change between
+ * releases — override any entry in the config file if yours differs.
+ */
+export declare const DEFAULT_CONFIG: Config;
+export declare function configPath(): string;
+/**
+ * Agents from the file replace same-named defaults outright rather than merging field by
+ * field, so overriding a command cannot leave half of the old one behind.
+ */
+export declare function loadConfig(path?: string): {
+    config: Config;
+    source: string;
+};

package/dist/config.js

@@ -0,0 +1,78 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Works with no configuration at all: the CLIs people already have, plus whatever Ollama
+ * is serving locally. An entry whose tool is not installed is simply reported as
+ * unavailable by list_agents, so shipping all four costs nothing.
+ *
+ * The flags are each tool's documented non-interactive mode, but they do change between
+ * releases — override any entry in the config file if yours differs.
+ */
+export const DEFAULT_CONFIG = {
+    maxOutputChars: 60_000,
+    maxConcurrent: 2,
+    agents: {
+        claude: {
+            description: 'Claude Code — refactoring, tests, reading large codebases',
+            // verified: claude -p reads the prompt from stdin, which lifts the argv size limit
+            command: ['claude', '-p'],
+            promptVia: 'stdin',
+            timeoutMs: 300_000,
+        },
+        codex: {
+            description: 'OpenAI Codex CLI — algorithms and single-file problems',
+            command: ['codex', 'exec', '{prompt}'],
+            timeoutMs: 300_000,
+        },
+        gemini: {
+            description: 'Google Gemini CLI — large context, whole-repo questions',
+            command: ['gemini', '-p', '{prompt}'],
+            timeoutMs: 300_000,
+        },
+        antigravity: {
+            // Google withdrew Gemini CLI from individual accounts, pointing them at Antigravity
+            // instead; its CLI reaches the same models through that login, with no API key
+            description: 'Gemini models through the Antigravity CLI',
+            command: ['agy', '-p', '{prompt}'],
+            timeoutMs: 300_000,
+        },
+        ollama: {
+            type: 'ollama',
+            description: 'A model running locally in Ollama — no account, no network, always awake',
+            timeoutMs: 300_000,
+        },
+    },
+};
+export function configPath() {
+    return process.env.MCPBRIDGE_CONFIG ?? join(homedir(), '.config', 'mcpbridge', 'config.json');
+}
+/**
+ * Agents from the file replace same-named defaults outright rather than merging field by
+ * field, so overriding a command cannot leave half of the old one behind.
+ */
+export function loadConfig(path = configPath()) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return { config: DEFAULT_CONFIG, source: 'defaults (no config file)' };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${path} is not valid JSON: ${error.message}`);
+    }
+    return {
+        config: {
+            maxOutputChars: parsed.maxOutputChars ?? DEFAULT_CONFIG.maxOutputChars,
+            maxConcurrent: Math.max(1, parsed.maxConcurrent ?? DEFAULT_CONFIG.maxConcurrent),
+            agents: { ...DEFAULT_CONFIG.agents, ...(parsed.agents ?? {}) },
+        },
+        source: path,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAiFjC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAW;IACpC,cAAc,EAAE,MAAM;IACtB,aAAa,EAAE,CAAC;IAChB,MAAM,EAAE;QACN,MAAM,EAAE;YACN,WAAW,EAAE,2DAA2D;YACxE,mFAAmF;YACnF,OAAO,EAAE,CAAC,QAAQ,EAAE,IAAI,CAAC;YACzB,SAAS,EAAE,OAAO;YAClB,SAAS,EAAE,OAAO;SACnB;QACD,KAAK,EAAE;YACL,WAAW,EAAE,wDAAwD;YACrE,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC;YACtC,SAAS,EAAE,OAAO;SACnB;QACD,MAAM,EAAE;YACN,WAAW,EAAE,yDAAyD;YACtE,OAAO,EAAE,CAAC,QAAQ,EAAE,IAAI,EAAE,UAAU,CAAC;YACrC,SAAS,EAAE,OAAO;SACnB;QACD,WAAW,EAAE;YACX,oFAAoF;YACpF,+EAA+E;YAC/E,WAAW,EAAE,2CAA2C;YACxD,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,CAAC;YAClC,SAAS,EAAE,OAAO;SACnB;QACD,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,0EAA0E;YACvF,SAAS,EAAE,OAAO;SACnB;KACF;CACF,CAAC;AAEF,MAAM,UAAU,UAAU;IACxB,OAAO,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;AAChG,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,IAAI,GAAG,UAAU,EAAE;IAC5C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,2BAA2B,EAAE,CAAC;IACzE,CAAC;IAED,IAAI,MAAuB,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAoB,CAAC;IAC9C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,uBAAwB,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO;QACL,MAAM,EAAE;YACN,cAAc,EAAE,MAAM,CAAC,cAAc,IAAI,cAAc,CAAC,cAAc;YACtE,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,aAAa,IAAI,cAAc,CAAC,aAAa,CAAC;YAChF,MAAM,EAAE,EAAE,GAAG,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE;SAC/D;QACD,MAAM,EAAE,IAAI;KACb,CAAC;AACJ,CAAC"}

package/dist/connect.d.ts

@@ -0,0 +1,35 @@
+import { type ToolContext } from './tools.js';
+export interface ConnectOptions {
+    /** the relay, as http(s):// or ws(s)://; a bare origin gets /agent appended */
+    relayUrl: string;
+    /** the agent token from the dashboard — identifies which account this machine serves */
+    token: string;
+    device?: string;
+    agentVersion: string;
+    context: ToolContext;
+    log?: (line: string) => void;
+    /** stop instead of reconnecting once the socket closes; for tests */
+    once?: boolean;
+    signal?: AbortSignal;
+    /** how often to push a fresh agent list while connected */
+    refreshMs?: number;
+    /** told when the relay welcomes this machine and when the session ends */
+    onState?: (state: {
+        connected: true;
+        device: string;
+    } | {
+        connected: false;
+        reason: string;
+    }) => void;
+}
+/** http -> ws, https -> wss; a URL with no path gets the relay's agent endpoint. */
+export declare function toWebSocketUrl(relayUrl: string): string;
+/**
+ * Keeps this machine connected to a relay and answers the calls it forwards.
+ *
+ * <p>The connection is outbound, so nothing here listens on a port and no firewall rule is
+ * needed. Each forwarded call runs the same executeTool as the local MCP server, so a
+ * delegation behaves identically whether it arrived from a client on this machine or from
+ * one on the other side of the relay.
+ */
+export declare function connectToRelay(options: ConnectOptions): Promise<void>;