botmancers 0.0.0-stage → 0.3.0

package/dist/redact.d.ts

@@ -0,0 +1,3 @@
+export declare const REDACTED = "[REDACTED]";
+export type Redactor = (text: string) => string;
+export declare function createRedactor(secrets: Array<string | undefined>): Redactor;

package/dist/redact.js

@@ -0,0 +1,16 @@
+// Secrets never reach logs or error messages: every line the bridge writes
+// passes through a redactor that knows the configured tokens.
+export const REDACTED = '[REDACTED]';
+export function createRedactor(secrets) {
+    const known = [...new Set(secrets.filter((secret) => !!secret && secret.length >= 4))]
+        .sort((a, b) => b.length - a.length);
+    return text => {
+        let out = text;
+        for (const secret of known)
+            out = out.split(secret).join(REDACTED);
+        // Belt and braces: any bearer credential or URL userinfo that slipped in.
+        return out
+            .replace(/(Bearer[ \t]+)[A-Za-z0-9._~+/=-]{12,}/gi, `$1${REDACTED}`)
+            .replace(/(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/gi, `$1${REDACTED}@`);
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,33 @@
+import { type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import type { BridgeConfig } from './config.js';
+import { type Redactor } from './redact.js';
+import { type Upstream } from './upstream.js';
+export declare const MCP_PATH = "/mcp";
+export declare const HEALTH_PATH = "/healthz";
+export declare const MAX_BODY_BYTES: number;
+export declare const JSON_RPC: {
+    parseError: number;
+    invalidRequest: number;
+    methodNotFound: number;
+    invalidParams: number;
+    internalError: number;
+};
+export interface Logger {
+    info(message: string): void;
+    error(message: string): void;
+}
+export interface BridgeOptions {
+    config: BridgeConfig;
+    logger?: Logger;
+    upstream?: Upstream;
+}
+export interface Bridge {
+    server: Server;
+    redact: Redactor;
+    upstream: Upstream;
+    listen(): Promise<AddressInfo>;
+    close(): Promise<void>;
+}
+export declare const defaultLogger: Logger;
+export declare function createBridge(options: BridgeOptions): Bridge;

package/dist/server.js

@@ -0,0 +1,240 @@
+// The standalone bridge: MCP Streamable HTTP at POST /mcp, stateless, with
+// application/json responses (no session id, no server-initiated SSE
+// stream, so GET and DELETE are 405), and an unauthenticated GET /healthz.
+//
+// initialize, ping, and tools/list are answered locally from the bundled
+// botmancers.mcp.v1 schema; tools/call for a contract tool is forwarded
+// unchanged to Botmancers' /api/v0/mcp with the service token. MCP clients
+// authenticate to the bridge with their own bearer token and never see the
+// service token.
+//
+// DNS-rebinding guard: when bound to a loopback address, Host must be a
+// loopback host; an Origin header, when present, must be exactly
+// http://<loopback Host>. The endpoint has no CORS support.
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { isLoopbackHost } from './config.js';
+import { MCP_CONTRACT, MCP_INSTRUCTIONS, MCP_PROTOCOL_VERSIONS, loadToolContract, negotiateProtocolVersion, packageVersion } from './contract.js';
+import { createRedactor } from './redact.js';
+import { UpstreamError, createUpstream } from './upstream.js';
+export const MCP_PATH = '/mcp';
+export const HEALTH_PATH = '/healthz';
+export const MAX_BODY_BYTES = 256 * 1024;
+export const JSON_RPC = { parseError: -32700, invalidRequest: -32600, methodNotFound: -32601, invalidParams: -32602, internalError: -32603 };
+function rpcError(id, code, message, data) {
+    return { jsonrpc: '2.0', id, error: { code, message, ...(data === undefined ? {} : { data }) } };
+}
+function sendJson(res, status, body, headers = {}) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store', ...headers });
+    res.end(text);
+}
+function envelope(res, status, code, message, headers = {}) {
+    sendJson(res, status, { error: { code, message } }, headers);
+}
+class BodyTooLarge extends Error {
+}
+function readBody(req) {
+    const declared = req.headers['content-length'];
+    if (declared !== undefined && !(/^\d+$/.test(declared.trim()) && Number(declared) <= MAX_BODY_BYTES)) {
+        return Promise.reject(new BodyTooLarge());
+    }
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.byteLength;
+            if (size > MAX_BODY_BYTES) {
+                req.pause();
+                reject(new BodyTooLarge());
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+function digest(value) {
+    return createHash('sha256').update(value, 'utf8').digest();
+}
+export const defaultLogger = {
+    info: message => process.stderr.write(`${message}\n`),
+    error: message => process.stderr.write(`${message}\n`),
+};
+export function createBridge(options) {
+    const { config } = options;
+    const redact = createRedactor([config.serviceToken, config.mcpToken]);
+    const base = options.logger ?? defaultLogger;
+    const logger = { info: m => base.info(redact(m)), error: m => base.error(redact(m)) };
+    const upstream = options.upstream ?? createUpstream({ botmancersUrl: config.botmancersUrl, serviceToken: config.serviceToken });
+    const contract = loadToolContract();
+    const toolNames = new Set(contract.tools.map(tool => tool.name));
+    const version = packageVersion();
+    const expectedToken = digest(config.mcpToken);
+    const loopbackOnly = isLoopbackHost(config.host);
+    function authorized(req) {
+        const match = /^Bearer[ \t]+(\S+)[ \t]*$/i.exec(req.headers.authorization ?? '');
+        if (!match || match[1].length > 4096)
+            return false;
+        return timingSafeEqual(digest(match[1]), expectedToken);
+    }
+    // Null when Host and Origin are trusted, else [code, message].
+    function rebindingRefusal(req) {
+        const host = (req.headers.host ?? '').trim().toLowerCase();
+        if (loopbackOnly && !isLoopbackHost(host.replace(/:\d+$/, ''))) {
+            return ['host_not_allowed', 'The request did not arrive on a loopback host.'];
+        }
+        const origin = req.headers.origin;
+        if (origin === undefined)
+            return null;
+        if (isLoopbackHost(host.replace(/:\d+$/, '')) && origin.trim().toLowerCase() === `http://${host}`)
+            return null;
+        return ['origin_not_allowed', 'Cross-origin requests are not accepted.'];
+    }
+    async function handleMessage(message) {
+        if (!message || typeof message !== 'object' || Array.isArray(message)) {
+            return { status: 400, body: rpcError(null, JSON_RPC.invalidRequest, 'Invalid Request') };
+        }
+        const { jsonrpc, id, method, params } = message;
+        const hasId = typeof id === 'string' || (typeof id === 'number' && Number.isFinite(id));
+        if (jsonrpc !== '2.0' || (id !== undefined && !hasId))
+            return { status: 400, body: rpcError(null, JSON_RPC.invalidRequest, 'Invalid Request') };
+        if (typeof method !== 'string') {
+            // A response to a server request; this server sends none.
+            return hasId ? { status: 202 } : { status: 400, body: rpcError(null, JSON_RPC.invalidRequest, 'Invalid Request') };
+        }
+        if (!hasId)
+            return { status: 202 };
+        const requestId = id;
+        const p = (params && typeof params === 'object' && !Array.isArray(params) ? params : {});
+        switch (method) {
+            case 'initialize':
+                return {
+                    status: 200,
+                    body: {
+                        jsonrpc: '2.0',
+                        id: requestId,
+                        result: {
+                            protocolVersion: negotiateProtocolVersion(p.protocolVersion),
+                            capabilities: { tools: { listChanged: false } },
+                            serverInfo: { name: 'botmancers', title: 'Botmancers', version },
+                            instructions: MCP_INSTRUCTIONS,
+                        },
+                    },
+                };
+            case 'ping':
+                return { status: 200, body: { jsonrpc: '2.0', id: requestId, result: {} } };
+            case 'tools/list':
+                return { status: 200, body: { jsonrpc: '2.0', id: requestId, result: { tools: contract.tools } } };
+            case 'tools/call': {
+                const name = p.name;
+                if (typeof name !== 'string' || !toolNames.has(name)) {
+                    return { status: 200, body: rpcError(requestId, JSON_RPC.invalidParams, `Unknown tool: ${typeof name === 'string' ? name.slice(0, 100) : String(name)}`) };
+                }
+                try {
+                    const answer = await upstream.send({ jsonrpc: '2.0', id: requestId, method, params: p });
+                    return { status: 200, body: answer };
+                }
+                catch (error) {
+                    if (!(error instanceof UpstreamError))
+                        throw error;
+                    logger.error(`botmancers: tools/call ${name} failed: ${error.message}`);
+                    if (error.kind === 'rate_limited') {
+                        return {
+                            status: 429,
+                            body: { error: { code: 'rate_limited', message: 'Too many tool calls; retry later.' } },
+                            headers: error.retryAfter ? { 'retry-after': error.retryAfter } : {},
+                        };
+                    }
+                    return { status: 200, body: rpcError(requestId, JSON_RPC.internalError, redact(error.message), { code: `botmancers_${error.kind}` }) };
+                }
+            }
+            default:
+                return { status: 200, body: rpcError(requestId, JSON_RPC.methodNotFound, 'Method not found') };
+        }
+    }
+    async function handleMcpPost(req, res) {
+        const refusal = rebindingRefusal(req);
+        if (refusal)
+            return envelope(res, 403, refusal[0], refusal[1]);
+        if (!authorized(req)) {
+            return envelope(res, 401, 'unauthenticated', 'Send Authorization: Bearer <BOTMANCERS_MCP_TOKEN>.', { 'www-authenticate': 'Bearer realm="botmancers"' });
+        }
+        const protocol = req.headers['mcp-protocol-version'];
+        if (typeof protocol === 'string' && !MCP_PROTOCOL_VERSIONS.includes(protocol)) {
+            return envelope(res, 400, 'unsupported_protocol_version', `Supported MCP protocol versions: ${MCP_PROTOCOL_VERSIONS.join(', ')}.`);
+        }
+        const accept = req.headers.accept;
+        if (accept && !/application\/json|application\/\*|\*\/\*/i.test(accept)) {
+            return envelope(res, 406, 'not_acceptable', 'This server answers with application/json.');
+        }
+        let text;
+        try {
+            text = await readBody(req);
+        }
+        catch (error) {
+            if (error instanceof BodyTooLarge) {
+                res.setHeader('connection', 'close');
+                return envelope(res, 413, 'payload_too_large', 'The message is too large.');
+            }
+            throw error;
+        }
+        let message;
+        try {
+            message = JSON.parse(text);
+        }
+        catch {
+            return sendJson(res, 400, rpcError(null, JSON_RPC.parseError, 'Parse error'));
+        }
+        if (Array.isArray(message))
+            return sendJson(res, 400, rpcError(null, JSON_RPC.invalidRequest, 'Batched messages are not supported.'));
+        const answer = await handleMessage(message);
+        if (answer.body === undefined) {
+            res.writeHead(answer.status);
+            res.end();
+            return;
+        }
+        sendJson(res, answer.status, answer.body, answer.headers);
+    }
+    const server = createServer((req, res) => {
+        const path = (req.url ?? '/').split('?')[0];
+        const route = async () => {
+            if (path === HEALTH_PATH) {
+                if (req.method !== 'GET' && req.method !== 'HEAD')
+                    return envelope(res, 405, 'method_not_allowed', 'Use GET.', { allow: 'GET, HEAD' });
+                return sendJson(res, 200, { status: 'ok', contract: MCP_CONTRACT, version });
+            }
+            if (path === MCP_PATH) {
+                if (req.method === 'POST')
+                    return handleMcpPost(req, res);
+                return envelope(res, 405, 'method_not_allowed', 'This MCP endpoint accepts POST only (no server-initiated stream or session).', { allow: 'POST' });
+            }
+            return envelope(res, 404, 'not_found', `Not found. The MCP endpoint is POST ${MCP_PATH}.`);
+        };
+        route().catch(error => {
+            logger.error(`botmancers: internal error: ${error.message}`);
+            if (!res.headersSent)
+                envelope(res, 500, 'internal_error', 'The request could not be processed.');
+            else
+                res.end();
+        });
+    });
+    return {
+        server,
+        redact,
+        upstream,
+        listen: () => new Promise((resolve, reject) => {
+            const onError = (error) => reject(error);
+            server.once('error', onError);
+            server.listen(config.port, config.host, () => {
+                server.off('error', onError);
+                resolve(server.address());
+            });
+        }),
+        close: () => new Promise(resolve => {
+            server.close(() => resolve());
+            server.closeAllConnections();
+        }),
+    };
+}

package/dist/setup.d.ts

@@ -0,0 +1,20 @@
+import { type HomePaths } from './home.js';
+export declare const BRIDGE_SERVICE_ID = "botmancers-bridge";
+export declare const SERVICE_TOKENS_ENV = "BOTMANCERS_SERVICE_TOKENS";
+export declare function serviceTokenDigest(token: string): string;
+export declare function generateToken(prefix: string): string;
+export interface SetupState {
+    ok: boolean;
+    problems: string[];
+}
+export declare function credentialState(paths: HomePaths): SetupState;
+export interface SetupResult {
+    created: boolean;
+    lines: string[];
+}
+export declare class SetupError extends Error {
+}
+export declare function runSetup(paths: HomePaths, ports: {
+    ui: number;
+    mcp: number;
+}): SetupResult;

package/dist/setup.js

@@ -0,0 +1,136 @@
+// `botmancers setup`: create BOTMANCERS_HOME owner-only and generate the two
+// local credentials the supervised product needs:
+//
+//   - the bridge-to-core service token: raw in config/bridge.env (the bridge
+//     sends it), only its SHA-256 digest in config/core.env as
+//     BOTMANCERS_SERVICE_TOKENS (what the engine reads);
+//   - the inbound MCP bearer token MCP clients send to the bridge, in
+//     config/bridge.env.
+//
+// Setup never writes Hermes, Agent Deck, or coding-agent credentials; it
+// prints where the operator adds them. Re-running keeps existing tokens and
+// re-tightens permissions; lines the operator added to core.env survive.
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { DEFAULT_PORT, ENV, MIN_MCP_TOKEN_LENGTH } from './config.js';
+import { HOME_DIRS, PRODUCT_HOST, ensurePrivateDir, readEnvFile, writePrivateFile } from './home.js';
+export const BRIDGE_SERVICE_ID = 'botmancers-bridge';
+export const SERVICE_TOKENS_ENV = 'BOTMANCERS_SERVICE_TOKENS';
+export function serviceTokenDigest(token) {
+    return `sha256:${createHash('sha256').update(token, 'utf8').digest('hex')}`;
+}
+export function generateToken(prefix) {
+    return `${prefix}_${randomBytes(32).toString('hex')}`;
+}
+// Whether config/core.env and config/bridge.env hold a consistent pair.
+export function credentialState(paths) {
+    const problems = [];
+    const bridge = readEnvFile(paths.bridgeEnv);
+    const core = readEnvFile(paths.coreEnv);
+    if (!bridge)
+        problems.push(`${paths.bridgeEnv} is missing`);
+    if (!core)
+        problems.push(`${paths.coreEnv} is missing`);
+    if (bridge && core) {
+        const service = bridge[ENV.serviceToken] ?? '';
+        const mcp = bridge[ENV.mcpToken] ?? '';
+        if (!service)
+            problems.push(`${ENV.serviceToken} is missing from bridge.env`);
+        if (mcp.length < MIN_MCP_TOKEN_LENGTH)
+            problems.push(`${ENV.mcpToken} is missing or too short in bridge.env`);
+        if (service && mcp === service)
+            problems.push('the MCP token must differ from the service token');
+        const listed = (core[SERVICE_TOKENS_ENV] ?? '').split(/[,\s]+/).filter(Boolean);
+        if (service && !listed.includes(`${BRIDGE_SERVICE_ID}=${serviceTokenDigest(service)}`)) {
+            problems.push(`core.env ${SERVICE_TOKENS_ENV} does not list the digest of the bridge service token`);
+        }
+        if (Object.values(core).some(value => value === service || value === mcp))
+            problems.push('core.env contains a raw bridge token');
+    }
+    return { ok: problems.length === 0, problems };
+}
+// Replace (or append) one KEY=value line, keeping every other line.
+function upsertLine(text, key, value) {
+    const line = `${key}=${value}`;
+    const pattern = new RegExp(`^\\s*(?:export\\s+)?${key}=.*$`, 'm');
+    if (pattern.test(text))
+        return text.replace(pattern, line);
+    return `${text.replace(/\n*$/, '\n')}${line}\n`;
+}
+const CORE_HEADER = `# Botmancers core engine configuration (generated by \`botmancers setup\`).
+# Read by \`botmancers start\`; variables exported in your shell take precedence,
+# except ${SERVICE_TOKENS_ENV}, which pairs with config/bridge.env.
+#
+# ${SERVICE_TOKENS_ENV} holds only the SHA-256 digest of the bridge's service
+# token; the raw token is in bridge.env.
+#
+# Hermes (conversational turns): add your gateway key here, e.g.
+#   HERMES_API_SERVER_KEY=<key from your Hermes gateway>
+#   HERMES_BASE_URL=http://127.0.0.1:8642
+# Agent Deck (coding-agent runs): add the run token Agent Deck issues, e.g.
+#   AGENT_DECK_RUN_TOKEN=<token from Agent Deck>
+# MCP coordinators reachable through botmancers_start_task (Agent names):
+#   BOTMANCERS_MCP_COORDINATORS=Tank
+`;
+const BRIDGE_HEADER = `# Botmancers MCP bridge credentials (generated by \`botmancers setup\`). Keep private.
+# ${ENV.serviceToken}: what the bridge sends to the core engine (core.env holds its digest).
+# ${ENV.mcpToken}: what MCP clients send to the bridge as Authorization: Bearer <token>.
+`;
+export class SetupError extends Error {
+}
+export function runSetup(paths, ports) {
+    try {
+        ensurePrivateDir(paths.home);
+        for (const dir of HOME_DIRS)
+            ensurePrivateDir(`${paths.home}/${dir}`);
+        let created = false;
+        if (!credentialState(paths).ok) {
+            const serviceToken = generateToken('bmsvc');
+            const mcpToken = generateToken('bmmcp');
+            const existingCore = existsSync(paths.coreEnv) ? readFileSync(paths.coreEnv, 'utf8') : CORE_HEADER;
+            writePrivateFile(paths.coreEnv, upsertLine(existingCore, SERVICE_TOKENS_ENV, `${BRIDGE_SERVICE_ID}=${serviceTokenDigest(serviceToken)}`));
+            writePrivateFile(paths.bridgeEnv, `${BRIDGE_HEADER}${ENV.serviceToken}=${serviceToken}\n${ENV.mcpToken}=${mcpToken}\n`);
+            created = true;
+        }
+        else {
+            // Re-tighten in case permissions were loosened.
+            writePrivateFile(paths.coreEnv, readFileSync(paths.coreEnv, 'utf8'));
+            writePrivateFile(paths.bridgeEnv, readFileSync(paths.bridgeEnv, 'utf8'));
+        }
+        const ui = `http://${PRODUCT_HOST}:${ports.ui}`;
+        const mcp = `http://${PRODUCT_HOST}:${ports.mcp}/mcp`;
+        const lines = [
+            created
+                ? `botmancers setup: initialized ${paths.home} (owner-only) and generated the bridge credentials.`
+                : `botmancers setup: ${paths.home} is already set up; kept the existing credentials and re-checked permissions.`,
+            `  ${paths.coreEnv}    core engine configuration (service-token digest only)`,
+            `  ${paths.bridgeEnv}  MCP bridge credentials (keep private)`,
+            '',
+            'Start Botmancers (UI, API, core engine, and MCP bridge):',
+            '  botmancers start --daemon --open',
+            `  UI ${ui}   MCP ${mcp}${ports.mcp === DEFAULT_PORT ? '' : ` (port ${ports.mcp})`}`,
+            '',
+            'MCP clients (Cursor, Agent Deck, ...):',
+            `  URL     ${mcp}`,
+            `  Header  Authorization: Bearer <${ENV.mcpToken} from ${paths.bridgeEnv}>`,
+            '',
+            'Hermes (conversational turns) is not configured by setup:',
+            `  add HERMES_API_SERVER_KEY=<your Hermes gateway key> (and HERMES_BASE_URL if not http://127.0.0.1:8642)`,
+            `  to ${paths.coreEnv}, then: botmancers stop && botmancers start --daemon`,
+            '',
+            'Agent Deck (coding-agent runs) is not configured by setup:',
+            '  install Agent Deck so `agent-deck` is on PATH and its server runs on http://127.0.0.1:1111,',
+            `  add AGENT_DECK_RUN_TOKEN=<token issued by Agent Deck> to ${paths.coreEnv}.`,
+            '',
+            'Check everything with: botmancers doctor',
+        ];
+        return { created, lines };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'EACCES' || code === 'EPERM' || code === 'EROFS' || code === 'ENOTDIR' || code === 'EEXIST') {
+            throw new SetupError(`cannot write BOTMANCERS_HOME ${paths.home} (${code}). Choose a writable directory with BOTMANCERS_HOME or fix its permissions.`);
+        }
+        throw error;
+    }
+}

package/dist/upgrade.d.ts

@@ -0,0 +1,15 @@
+import { type NpmRunner, type StageDeps } from './managed.js';
+export interface UpgradeIo {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+}
+export interface UpgradeDeps extends StageDeps {
+    latest?: () => Promise<string>;
+    globalNpm?: NpmRunner;
+    confirm?: (question: string) => Promise<boolean>;
+    updateLockTimeoutMs?: number;
+}
+export declare const INSTALL_HELP = "Usage: botmancers install [--to VERSION] [--migrate-cli] [--purge-global]\n\nInstalls botmancers@VERSION (default: npm latest) into ~/.botmancers/versions/VERSION,\npoints ~/.botmancers/current at it, and writes the launcher ~/.local/bin/botmancers.\nYour data, configuration, logs, and workdirs under ~/.botmancers are not touched.\n`--to` an older installed version rolls back to it.\n\n  --to VERSION     install this exact version instead of latest\n  --migrate-cli    explain how to make the launcher win over an npm-global botmancers on PATH\n  --purge-global   also run `npm uninstall -g botmancers` (the only option that does)\n\nAutomatic updates are on for managed installs: at most one npm check a day, a\nbackground download, and activation at the next `botmancers start`.\nTurn them off with BOTMANCERS_DISABLE_AUTOUPDATER=1.\n";
+export declare const UPGRADE_HELP = "Usage: botmancers upgrade [--check] [--to VERSION] [--yes]\n\n  managed      download and verify the release, then activate it (or, while the\n               product runs, stage it to activate at the next start)\n  npm-global   npm install -g botmancers@VERSION (asks first unless --yes)\n  other        report how this copy was installed; never changes it\n\n  --check        report the installed, latest, and pending versions only\n  --to VERSION   this exact version (an older one rolls back)\n  --yes          do not ask before npm install -g\n";
+export declare function runInstall(argv: string[], env: NodeJS.ProcessEnv, io: UpgradeIo, deps?: UpgradeDeps): Promise<number>;
+export declare function runUpgrade(argv: string[], env: NodeJS.ProcessEnv, io: UpgradeIo, deps?: UpgradeDeps): Promise<number>;