@mcpbridgeapp/cli 0.0.0-stage → 0.1.1

package/dist/agents/cli.js

@@ -0,0 +1,270 @@
+import { spawn } from 'node:child_process';
+import { constants, readFileSync } from 'node:fs';
+import { access } from 'node:fs/promises';
+import { delimiter, dirname, join, sep } from 'node:path';
+import { parseShimTarget } from './shim.js';
+import { cleanDiagnostics, troubleOnSuccess } from './outcome.js';
+import { permissionsFor } from './permissions.js';
+import { effectiveTimeout, failed, truncate } from './types.js';
+export const PROMPT_PLACEHOLDER = '{prompt}';
+/** Colour and spinners in an answer are noise; most CLIs honour these. */
+const QUIET_ENV = { NO_COLOR: '1', FORCE_COLOR: '0', TERM: 'dumb' };
+/**
+ * An agent that is a command-line tool. The command comes from configuration and the
+ * prompt only ever fills {prompt} or goes down stdin — never through a shell, so nothing
+ * in a prompt can be read as a shell metacharacter.
+ */
+export class CliAgent {
+    name;
+    config;
+    maxOutputChars;
+    requires;
+    readsFiles = true;
+    permissions;
+    constructor(name, config, maxOutputChars) {
+        this.name = name;
+        this.config = config;
+        this.maxOutputChars = maxOutputChars;
+        if (config.command.length === 0) {
+            throw new Error(`agent "${name}": command must not be empty`);
+        }
+        if (this.promptVia === 'argv' && !config.command.some((p) => p.includes(PROMPT_PLACEHOLDER))) {
+            throw new Error(`agent "${name}": command needs one ${PROMPT_PLACEHOLDER} element, or promptVia: "stdin"`);
+        }
+        this.requires = config.command[0];
+        this.permissions = permissionsFor(config);
+    }
+    get writesFiles() {
+        return this.permissions.writesFiles;
+    }
+    get runsCommands() {
+        return this.permissions.runsCommands;
+    }
+    get timeoutMs() {
+        return this.config.timeoutMs ?? 300_000;
+    }
+    get promptVia() {
+        return this.config.promptVia ?? 'argv';
+    }
+    get description() {
+        return this.config.description ?? `the ${this.requires} command`;
+    }
+    async probe() {
+        const resolved = await resolveOnPath(this.requires);
+        if (!resolved) {
+            return { available: false, detail: `${this.requires} is not on PATH — install it or fix the command` };
+        }
+        if (!needsAShell(resolved)) {
+            return { available: true, detail: `${this.requires} found at ${resolved}` };
+        }
+        const behindShim = readShim(resolved);
+        if (!behindShim) {
+            return { available: false, detail: batchFileAdvice(this.requires, resolved) };
+        }
+        // name the script, not the interpreter: "a shim for node.exe" says nothing about
+        // which program is actually going to run
+        const target = behindShim.prefix[0] ?? behindShim.command;
+        const via = behindShim.prefix.length > 0 ? `, run with ${behindShim.command}` : '';
+        return { available: true, detail: `${this.requires} is a shim for ${target}${via}` };
+    }
+    async run(prompt, options) {
+        const resolved = await resolveOnPath(this.requires);
+        let replacement = null;
+        if (resolved && needsAShell(resolved)) {
+            replacement = readShim(resolved);
+            if (!replacement)
+                return failed(this.name, batchFileAdvice(this.requires, resolved));
+        }
+        return this.spawnAgent(prompt, options, replacement);
+    }
+    spawnAgent(prompt, options, replacement) {
+        const viaStdin = this.promptVia === 'stdin';
+        const configured = viaStdin
+            ? [...this.config.command]
+            : this.config.command.map((part) => part.replaceAll(PROMPT_PLACEHOLDER, prompt));
+        // the shim's own argv[0] is replaced by what it would have run, keeping the agent's
+        // own flags after it
+        const argv = [
+            ...(replacement ? [replacement.command, ...replacement.prefix, ...configured.slice(1)] : configured),
+            // what the owner allowed it, in this CLI's own flags
+            ...this.permissions.args,
+        ];
+        const [command, ...args] = argv;
+        const timeoutMs = effectiveTimeout(this.config.timeoutMs, options);
+        const cwd = options.cwd ?? this.config.cwd;
+        const started = Date.now();
+        return new Promise((resolve) => {
+            let child;
+            try {
+                child = spawn(command, args, {
+                    cwd,
+                    env: { ...process.env, ...QUIET_ENV, ...this.permissions.env, ...(this.config.env ?? {}) },
+                    // own process group, so a timeout can take the whole tree down: killing just the
+                    // child leaves grandchildren alive, and an orphan holding the pipe keeps us
+                    // waiting for its lifetime
+                    detached: process.platform !== 'win32',
+                    stdio: [viaStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+                });
+            }
+            catch (error) {
+                resolve(failed(this.name, this.startupAdvice(command, error, prompt)));
+                return;
+            }
+            let stdout = '';
+            let stderr = '';
+            let settled = false;
+            const finish = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(result);
+            };
+            // stdout and stderr are consumed as they arrive, so neither pipe can fill and stall
+            // the child while we are busy with the other
+            child.stdout?.on('data', (chunk) => {
+                const text = chunk.toString('utf8');
+                stdout += text;
+                options.onOutput?.(text);
+            });
+            child.stderr?.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
+            if (viaStdin && child.stdin) {
+                child.stdin.on('error', () => { });
+                child.stdin.end(prompt, 'utf8');
+            }
+            const timer = setTimeout(() => {
+                killTree(child.pid);
+                // what it had written by then is often most of an answer; throwing it away left a
+                // caller with nothing after five minutes of real work
+                const partial = truncate(stdout, this.maxOutputChars);
+                finish({
+                    ...failed(this.name, `${this.name} did not finish within ${Math.round(timeoutMs / 1000)} s and was stopped.` +
+                        (partial.text ? ' What it had written by then is in "output"; it is incomplete.' : ' It had written nothing yet.') +
+                        ' Give it a smaller task, or a longer timeout in its config.', Date.now() - started, true),
+                    output: partial.text,
+                    outputTruncated: partial.truncated,
+                });
+            }, timeoutMs);
+            child.on('error', (error) => {
+                finish(failed(this.name, this.startupAdvice(command, error, prompt), Date.now() - started));
+            });
+            child.on('close', (code) => {
+                const body = truncate(stdout, this.maxOutputChars);
+                // a CLI that failed often prints its error on stdout, not stderr
+                const failureText = stderr.trim() ? stderr : stdout;
+                const trouble = code === 0 ? troubleOnSuccess(stderr) : null;
+                finish({
+                    agent: this.name,
+                    succeeded: code === 0,
+                    output: body.text,
+                    diagnostics: code === 0
+                        ? ''
+                        : `${this.name} exited with code ${code}.\n${cleanDiagnostics(failureText, prompt)}`.trim(),
+                    notes: trouble
+                        ? `${this.name} exited normally but printed errors while running; a failing hook can stop it reading anything, so check the answer before trusting it:\n${trouble}`
+                        : '',
+                    durationMs: Date.now() - started,
+                    timedOut: false,
+                    outputTruncated: body.truncated,
+                });
+            });
+        });
+    }
+    startupAdvice(command, error, prompt) {
+        return startupAdvice(this.name, command, error, prompt);
+    }
+}
+/**
+ * Both of these mean the operating system refused an over-long argument list, which a
+ * prompt carrying file contents reaches easily. POSIX reports E2BIG and Windows
+ * ENAMETOOLONG; treating only one of them as the size problem left Windows users with
+ * "is it installed?", which is the wrong thing to go and check.
+ */
+const ARG_TOO_LONG = new Set(['E2BIG', 'ENAMETOOLONG']);
+/**
+ * Turns a spawn failure into something the caller can act on. The size limit varies by
+ * platform — roughly 128KB per argument on Linux, about 1MB on macOS, and as little as
+ * 32KB on Windows — so the advice names the setting that removes it rather than a number.
+ */
+export function startupAdvice(agent, command, error, prompt) {
+    if (error.code && ARG_TOO_LONG.has(error.code)) {
+        return (`the prompt is too large to pass as a command-line argument (${prompt.length} characters; ` +
+            `the operating system's limit is as low as 32KB on Windows). Set "promptVia": "stdin" for ` +
+            `agent "${agent}" if ${command} reads its prompt from a pipe, or send a shorter prompt.`);
+    }
+    return `could not start ${command}. Is it installed and on PATH? (${error.message})`;
+}
+/**
+ * Reads what a Windows shim would have run. Reading it is safe where executing it is not:
+ * nothing from the prompt reaches the file, and the program it names is spawned directly.
+ */
+function readShim(shimPath) {
+    try {
+        return parseShimTarget(readFileSync(shimPath, 'utf8'), dirname(shimPath), process.execPath);
+    }
+    catch {
+        return null;
+    }
+}
+/** Kills the process group on POSIX, the tree via taskkill on Windows. */
+function killTree(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        if (process.platform === 'win32') {
+            spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
+        }
+        else {
+            process.kill(-pid, 'SIGKILL');
+        }
+    }
+    catch {
+        // already gone
+    }
+}
+/**
+ * A .cmd or .bat can only be run through a shell, and running the prompt through a shell
+ * is exactly what this program must never do: quoting rules for batch files are their own
+ * minefield (see CVE-2024-27980). So such an agent is refused with the fix, rather than
+ * made to work unsafely or left to fail as a bare ENOENT.
+ */
+export function needsAShell(resolvedPath) {
+    if (process.platform !== 'win32')
+        return false;
+    const lower = resolvedPath.toLowerCase();
+    return lower.endsWith('.cmd') || lower.endsWith('.bat');
+}
+function batchFileAdvice(executable, resolved) {
+    return (`${executable} resolves to ${resolved}, a Windows batch shim whose target could not be ` +
+        `read, and a shim can only run through a shell — which a prompt must not touch. Point ` +
+        `this agent at the real executable instead, e.g. ` +
+        `"command": ["C:\\\\path\\\\to\\\\${executable}.exe", "{prompt}"].`);
+}
+export async function resolveOnPath(executable) {
+    if (executable.includes(sep) || executable.includes('/')) {
+        return (await accessible(executable)) ? executable : null;
+    }
+    const dirs = (process.env.PATH ?? '').split(delimiter).filter(Boolean);
+    const suffixes = process.platform === 'win32' ? ['.exe', '.com', '.cmd', '.bat', ''] : [''];
+    for (const dir of dirs) {
+        for (const suffix of suffixes) {
+            const candidate = join(dir, executable + suffix);
+            if (await accessible(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+export async function onPath(executable) {
+    return (await resolveOnPath(executable)) !== null;
+}
+async function accessible(path) {
+    try {
+        await access(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/agents/cli.js.map

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

package/dist/agents/health.d.ts

@@ -0,0 +1,38 @@
+import type { FailureKind } from './outcome.js';
+import type { AgentResult } from './types.js';
+/**
+ * What the bridge has learned about each agent by using it.
+ *
+ * <p>Probing can only say a command exists; whether its account works shows up when it is
+ * asked to do something. In the field report, three of four agents listed as available
+ * failed at call time -- an exhausted quota, an ineligible account tier, a broken hook --
+ * and each was found by spending a call. Quota and sign-in failures are durable: they fail
+ * the same way on the next call. So the last one is remembered and shown by list_agents,
+ * which lets a caller route around it before spending anything.
+ */
+export interface AgentHealth {
+    calls: number;
+    failures: number;
+    lastSuccessAt?: number;
+    lastFailure?: {
+        kind: FailureKind;
+        message: string;
+        at: number;
+        retryAt?: string;
+    };
+    /**
+     * Which came last, by order of recording rather than by clock: two calls can finish in
+     * the same millisecond, and a success recorded after a failure must still clear it.
+     */
+    lastWasFailure: boolean;
+}
+export type AgentState = 'ready' | 'unavailable' | 'quota-exhausted' | 'sign-in-failed' | 'directory-not-trusted';
+export declare class HealthStore {
+    private readonly byAgent;
+    record(name: string, result: AgentResult, now?: number): void;
+    get(name: string): AgentHealth | undefined;
+    /** Forgets an agent, for when its configuration changed and the old lessons may not hold. */
+    forget(name: string): void;
+    /** The state a caller should act on: a durable failure newer than the last success wins. */
+    state(name: string, probedAvailable: boolean, now?: number): AgentState;
+}

package/dist/agents/health.js

@@ -0,0 +1,53 @@
+import { classifyFailure } from './outcome.js';
+/** How long a failure keeps an agent marked unusable when no success has cleared it. */
+const REMEMBER_MS = {
+    quota: 60 * 60 * 1000,
+    auth: 6 * 60 * 60 * 1000,
+    trust: 6 * 60 * 60 * 1000,
+    other: 0,
+};
+export class HealthStore {
+    byAgent = new Map();
+    record(name, result, now = Date.now()) {
+        const health = this.byAgent.get(name) ?? { calls: 0, failures: 0, lastWasFailure: false };
+        health.calls += 1;
+        if (result.succeeded) {
+            health.lastSuccessAt = now;
+            health.lastWasFailure = false;
+        }
+        else if (!result.timedOut) {
+            health.lastWasFailure = true;
+            // a timeout says the task was big, not that the agent is broken
+            health.failures += 1;
+            const { kind, retryAt } = classifyFailure(result.diagnostics);
+            const firstLine = result.diagnostics.split('\n').find((l) => l.trim()) ?? result.diagnostics;
+            health.lastFailure = { kind, message: firstLine.slice(0, 300), at: now, ...(retryAt ? { retryAt } : {}) };
+        }
+        this.byAgent.set(name, health);
+    }
+    get(name) {
+        return this.byAgent.get(name);
+    }
+    /** Forgets an agent, for when its configuration changed and the old lessons may not hold. */
+    forget(name) {
+        this.byAgent.delete(name);
+    }
+    /** The state a caller should act on: a durable failure newer than the last success wins. */
+    state(name, probedAvailable, now = Date.now()) {
+        if (!probedAvailable)
+            return 'unavailable';
+        const health = this.byAgent.get(name);
+        const failure = health?.lastFailure;
+        if (!failure || !health.lastWasFailure)
+            return 'ready';
+        if (now - failure.at > REMEMBER_MS[failure.kind])
+            return 'ready';
+        switch (failure.kind) {
+            case 'quota': return 'quota-exhausted';
+            case 'auth': return 'sign-in-failed';
+            case 'trust': return 'directory-not-trusted';
+            default: return 'ready';
+        }
+    }
+}
+//# sourceMappingURL=health.js.map

package/dist/agents/health.js.map

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

package/dist/agents/ollama.d.ts

@@ -0,0 +1,27 @@
+import type { OllamaAgentConfig } from '../config.js';
+import { type Agent, type AgentResult, type RunOptions } from './types.js';
+/**
+ * A model served locally by Ollama. The only agent that needs neither an account nor a
+ * network, so it is the one that is always awake — useful as a fallback when no vendor CLI
+ * is installed, and for work that should not leave the machine.
+ */
+export declare class OllamaAgent implements Agent {
+    readonly name: string;
+    private readonly config;
+    private readonly maxOutputChars;
+    readonly requires: string;
+    readonly readsFiles = false;
+    readonly writesFiles = false;
+    readonly runsCommands = false;
+    get timeoutMs(): number;
+    constructor(name: string, config: OllamaAgentConfig, maxOutputChars: number);
+    private get baseUrl();
+    get description(): string;
+    probe(): Promise<{
+        available: boolean;
+        detail: string;
+    }>;
+    run(prompt: string, options: RunOptions): Promise<AgentResult>;
+    /** null means Ollama is not reachable, as opposed to reachable with nothing installed. */
+    private installedModels;
+}

package/dist/agents/ollama.js

@@ -0,0 +1,118 @@
+import { effectiveTimeout, failed, truncate } from './types.js';
+const DEFAULT_BASE_URL = 'http://127.0.0.1:11434';
+/**
+ * A model served locally by Ollama. The only agent that needs neither an account nor a
+ * network, so it is the one that is always awake — useful as a fallback when no vendor CLI
+ * is installed, and for work that should not leave the machine.
+ */
+export class OllamaAgent {
+    name;
+    config;
+    maxOutputChars;
+    requires;
+    // an HTTP model sees only what is in the prompt; a directory means nothing to it
+    readsFiles = false;
+    writesFiles = false;
+    runsCommands = false;
+    get timeoutMs() {
+        return this.config.timeoutMs ?? 300_000;
+    }
+    constructor(name, config, maxOutputChars) {
+        this.name = name;
+        this.config = config;
+        this.maxOutputChars = maxOutputChars;
+        this.requires = `${this.baseUrl}`;
+    }
+    get baseUrl() {
+        return (this.config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+    }
+    get description() {
+        const model = this.config.model ? ` (${this.config.model})` : ' (first installed model)';
+        return (this.config.description ?? 'A model running locally in Ollama') + model;
+    }
+    async probe() {
+        const models = await this.installedModels();
+        if (models === null) {
+            return { available: false, detail: `no Ollama responding at ${this.baseUrl} — start it with "ollama serve"` };
+        }
+        if (models.length === 0) {
+            return { available: false, detail: `Ollama is running but has no models — pull one, e.g. "ollama pull qwen3"` };
+        }
+        if (this.config.model && !models.includes(this.config.model)) {
+            return {
+                available: false,
+                detail: `model "${this.config.model}" is not installed. Available: ${models.join(', ')}`,
+            };
+        }
+        return { available: true, detail: `Ollama at ${this.baseUrl}, using ${this.config.model ?? models[0]}` };
+    }
+    async run(prompt, options) {
+        const started = Date.now();
+        // the caller may have passed a directory expecting the agent to read it; saying so
+        // beats letting it wonder why the answer ignores the code
+        const note = options.cwd
+            ? `workingDirectory (${options.cwd}) was ignored: ${this.name} is a model behind an HTTP ` +
+                `API and cannot read files. Inline the content you want it to see in the prompt, or ` +
+                `delegate to an agent that list_agents reports with "readsFiles": true.`
+            : '';
+        const timeoutMs = effectiveTimeout(this.config.timeoutMs, options);
+        let model = this.config.model;
+        if (!model) {
+            const models = await this.installedModels();
+            if (models === null) {
+                return failed(this.name, `no Ollama responding at ${this.baseUrl} — start it with "ollama serve"`, Date.now() - started);
+            }
+            if (models.length === 0) {
+                return failed(this.name, 'Ollama has no models installed — pull one, e.g. "ollama pull qwen3"', Date.now() - started);
+            }
+            model = models[0];
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(`${this.baseUrl}/api/generate`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ model, prompt, stream: false }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                return failed(this.name, `Ollama returned HTTP ${response.status}: ${truncate(await response.text(), 1_000).text}`, Date.now() - started);
+            }
+            const payload = (await response.json());
+            const body = truncate(payload.response ?? '', this.maxOutputChars);
+            return {
+                agent: this.name, succeeded: true, output: body.text, diagnostics: '', notes: note,
+                durationMs: Date.now() - started, timedOut: false, outputTruncated: body.truncated,
+            };
+        }
+        catch (error) {
+            const aborted = controller.signal.aborted;
+            return failed(this.name, aborted
+                ? `${this.name} did not answer within ${timeoutMs}ms. Try a smaller task or a smaller model.`
+                : `could not reach Ollama at ${this.baseUrl}: ${error.message}`, Date.now() - started, aborted);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** null means Ollama is not reachable, as opposed to reachable with nothing installed. */
+    async installedModels() {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 3_000);
+        try {
+            const response = await fetch(`${this.baseUrl}/api/tags`, { signal: controller.signal });
+            if (!response.ok)
+                return null;
+            const payload = (await response.json());
+            return (payload.models ?? []).map((m) => m.name).filter((n) => Boolean(n));
+        }
+        catch {
+            return null;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=ollama.js.map

package/dist/agents/ollama.js.map

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

package/dist/agents/openai.d.ts

@@ -0,0 +1,35 @@
+import type { OpenAiAgentConfig } from '../config.js';
+import { type Agent, type AgentResult, type RunOptions } from './types.js';
+/**
+ * An agent reached over an OpenAI-compatible chat-completions API.
+ *
+ * <p>This is the only door some providers leave open — xAI publishes no CLI, so Grok is
+ * reachable this way or not at all. One adapter serves all of them because the request
+ * shape is the same; only the base URL, model and key change.
+ *
+ * <p>The key is never put in a result, a note or a log: errors quote the provider's
+ * message, never the request.
+ */
+export declare class OpenAiAgent implements Agent {
+    readonly name: string;
+    private readonly config;
+    private readonly maxOutputChars;
+    readonly requires: string;
+    readonly readsFiles = false;
+    readonly writesFiles = false;
+    readonly runsCommands = false;
+    get timeoutMs(): number;
+    constructor(name: string, config: OpenAiAgentConfig, maxOutputChars: number);
+    private get endpoint();
+    get description(): string;
+    /** Resolved at call time, so a key exported after startup is picked up. */
+    private key;
+    private missingKeyDetail;
+    probe(): Promise<{
+        available: boolean;
+        detail: string;
+    }>;
+    run(prompt: string, options: RunOptions): Promise<AgentResult>;
+    /** null means the endpoint does not offer a usable /models listing. */
+    private listModels;
+}