botmancers 0.1.0 → 0.4.2

package/dist/server.js

@@ -3,8 +3,9 @@
 // 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
+// botmancers.mcp.v2 schema (every v1 tool included); tools/call for any
+// contract tool, v1 or v2, 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.
 //
@@ -14,7 +15,7 @@
 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 { MCP_CONTRACT, MCP_CONTRACTS, 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';
@@ -203,7 +204,7 @@ export function createBridge(options) {
             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 });
+                return sendJson(res, 200, { status: 'ok', contract: MCP_CONTRACT, contracts: [...MCP_CONTRACTS], version });
             }
             if (path === MCP_PATH) {
                 if (req.method === 'POST')

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>;

package/dist/upgrade.js

@@ -0,0 +1,275 @@
+// `botmancers install` and `botmancers upgrade`: the explicit managed-install
+// commands (./managed holds the release tree, launcher, and updater).
+//
+//   install [--to VERSION] [--migrate-cli] [--purge-global]
+//       Download botmancers@VERSION (default: npm latest) into
+//       <home>/versions/VERSION, point <home>/current at it, and write the
+//       ~/.local/bin/botmancers launcher. `--to` an installed older version is
+//       the rollback.
+//   upgrade [--check] [--to VERSION] [--yes]
+//       managed: download, verify, and activate; npm-global: the prompted
+//       `npm install -g botmancers@VERSION`; anything else: guidance only.
+//
+// Neither command touches user state under <home>. A release is never made
+// current under a live product: it is recorded as pending and activates at
+// the next `botmancers start`.
+import { createInterface } from 'node:readline';
+import { delimiter } from 'node:path';
+import { packageVersion } from './contract.js';
+import { MANAGED_INSTALL_COMMAND, PACKAGE_NAME, RESTART_ACTION, activateRelease, botmancersOnPath, compareSemver, currentManagedVersion, detectInstallKind, fetchLatestVersion, isAutoupdaterDisabled, isSemver, managedPaths, readUpdateState, runNpm, stageRelease, waitForFileLock, writeLauncher, writeUpdateState, } from './managed.js';
+import { inspect, productContext, startLockTimeout } from './product.js';
+const UPDATE_LOCK_TIMEOUT_MS = 30 * 60 * 1000;
+export const INSTALL_HELP = `Usage: botmancers install [--to VERSION] [--migrate-cli] [--purge-global]
+
+Installs botmancers@VERSION (default: npm latest) into ~/.botmancers/versions/VERSION,
+points ~/.botmancers/current at it, and writes the launcher ~/.local/bin/botmancers.
+Your data, configuration, logs, and workdirs under ~/.botmancers are not touched.
+\`--to\` an older installed version rolls back to it.
+
+  --to VERSION     install this exact version instead of latest
+  --migrate-cli    explain how to make the launcher win over an npm-global botmancers on PATH
+  --purge-global   also run \`npm uninstall -g botmancers\` (the only option that does)
+
+Automatic updates are on for managed installs: at most one npm check a day, a
+background download, and activation at the next \`botmancers start\`.
+Turn them off with BOTMANCERS_DISABLE_AUTOUPDATER=1.
+`;
+export const UPGRADE_HELP = `Usage: botmancers upgrade [--check] [--to VERSION] [--yes]
+
+  managed      download and verify the release, then activate it (or, while the
+               product runs, stage it to activate at the next start)
+  npm-global   npm install -g botmancers@VERSION (asks first unless --yes)
+  other        report how this copy was installed; never changes it
+
+  --check        report the installed, latest, and pending versions only
+  --to VERSION   this exact version (an older one rolls back)
+  --yes          do not ask before npm install -g
+`;
+class ArgError extends Error {
+}
+function parseFlags(argv, flags) {
+    const set = new Set();
+    let to;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--to') {
+            to = argv[++i];
+            if (!isSemver(to))
+                throw new ArgError('--to needs a version such as 0.3.0.');
+        }
+        else if (flags.includes(arg))
+            set.add(arg);
+        else
+            throw new ArgError(/^--?[a-z][a-z0-9-]{0,38}$/.test(arg) ? `Unknown argument ${JSON.stringify(arg)}.` : 'Unexpected argument (value not shown).');
+    }
+    return { to, set };
+}
+function ttyConfirm(question) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return Promise.resolve(false);
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise(resolve => rl.question(question, answer => {
+        rl.close();
+        resolve(/^y/i.test(answer.trim()));
+    }));
+}
+async function resolveTarget(env, to, deps) {
+    return to ?? await (deps.latest ?? (() => fetchLatestVersion(env, 10_000)))();
+}
+// Whether a product started from this home is live (any owned or unverifiable
+// process); then `current` must not move beneath it.
+async function productLive(env) {
+    const view = await inspect(productContext(env, { stdout: () => { }, stderr: () => { } }));
+    return view.state !== 'stopped';
+}
+// Makes a complete staged release current, or records it as pending while
+// the product runs. Rolling back marks the newer version declined (and drops
+// a newer pending release), so the auto-updater does not reinstate it at the
+// next start. The caller holds update.lock; the stopped proof and the switch
+// happen inside start.lock, so no start can launch the old release between
+// them.
+async function placeRelease(paths, env, version, io, clearDeclined) {
+    const previous = currentManagedVersion(paths);
+    const state = readUpdateState(paths);
+    const newest = [previous, state.pendingVersion, state.declinedVersion].filter(isSemver).sort(compareSemver).pop() ?? null;
+    const declinedVersion = newest && compareSemver(version, newest) < 0 ? newest : clearDeclined ? null : state.declinedVersion;
+    const supersedesPending = isSemver(state.pendingVersion) && state.pendingVersion !== version
+        ? { pendingVersion: null, pendingIntegrity: null, stagedAt: null } : {};
+    const startLock = previous && previous !== version
+        ? await waitForFileLock(paths.startLock, {
+            timeoutMs: startLockTimeout(env),
+            onWait: () => io.stdout('botmancers: waiting for a botmancers start in progress...\n'),
+        })
+        : null;
+    try {
+        // Without start.lock a start is in progress: as good as live.
+        if (previous && previous !== version && (!startLock || await productLive(env))) {
+            if (isAutoupdaterDisabled(env)) {
+                io.stderr(`botmancers: ${version} is downloaded, but botmancers ${previous} is running and automatic activation is off (BOTMANCERS_DISABLE_AUTOUPDATER). Run \`botmancers stop\`, then \`botmancers upgrade --to ${version}\`.\n`);
+                return 'blocked';
+            }
+            writeUpdateState(paths, { pendingVersion: version, pendingIntegrity: null, stagedAt: new Date().toISOString(), declinedVersion });
+            io.stdout(`botmancers: ${version} is staged; botmancers ${previous} keeps running. Restart once to activate it: ${RESTART_ACTION}\n`);
+            return 'pending';
+        }
+        writeUpdateState(paths, { ...supersedesPending, declinedVersion });
+        activateRelease(paths, version);
+        io.stdout(`botmancers: activated ${version}${previous && previous !== version ? ` (was ${previous})` : ''}; ${paths.current} -> versions/${version}\n`);
+        return 'activated';
+    }
+    finally {
+        startLock?.release();
+    }
+}
+// Serializes an explicit staging and placement with the background updater
+// and any other install/upgrade of this home (update.lock).
+async function withUpdateLock(paths, io, deps, body) {
+    const lock = await waitForFileLock(paths.lock, {
+        timeoutMs: deps.updateLockTimeoutMs ?? UPDATE_LOCK_TIMEOUT_MS,
+        onWait: () => io.stdout(`botmancers: waiting for a background update or another install to finish (${paths.lock})...\n`),
+    });
+    if (!lock) {
+        io.stderr(`botmancers: another update of ${paths.home} is still running (${paths.lock}); try again when it finishes.\n`);
+        return null;
+    }
+    try {
+        return await body();
+    }
+    finally {
+        lock.release();
+    }
+}
+async function stage(paths, env, version, io, deps) {
+    try {
+        const staged = await stageRelease(paths, env, version, deps);
+        io.stdout(staged.reused
+            ? `botmancers: ${version} is already installed at ${staged.dir}\n`
+            : `botmancers: downloaded ${PACKAGE_NAME}@${version} (${staged.integrity}) into ${staged.dir}\n`);
+        return true;
+    }
+    catch (error) {
+        io.stderr(`botmancers: could not install ${PACKAGE_NAME}@${version}: ${error.message}\n`);
+        return false;
+    }
+}
+function pathAdvice(paths, env, io, migrate) {
+    io.stdout(`Launcher: ${paths.launcher}\n`);
+    const dirs = (env.PATH ?? '').split(delimiter);
+    if (!dirs.includes(paths.localBin))
+        io.stdout(`${paths.localBin} is not on PATH. Add it, e.g.: export PATH="${paths.localBin}:$PATH"\n`);
+    const first = botmancersOnPath(env)[0];
+    if (first && first !== paths.launcher) {
+        io.stdout(`Note: \`botmancers\` currently resolves to ${first}, which shadows the launcher.\n`);
+        if (migrate)
+            io.stdout(`To migrate: put ${paths.localBin} before ${first.slice(0, first.lastIndexOf('/'))} on PATH, or run \`botmancers install --purge-global\` to remove the npm-global copy.\n`);
+    }
+}
+export async function runInstall(argv, env, io, deps = {}) {
+    if (argv.includes('-h') || argv.includes('--help')) {
+        io.stdout(INSTALL_HELP);
+        return 0;
+    }
+    let flags;
+    try {
+        flags = parseFlags(argv, ['--migrate-cli', '--purge-global']);
+    }
+    catch (error) {
+        io.stderr(`botmancers install: ${error.message} Run botmancers install --help.\n`);
+        return 2;
+    }
+    const paths = managedPaths(env);
+    let version;
+    try {
+        version = await resolveTarget(env, flags.to, deps);
+    }
+    catch (error) {
+        io.stderr(`botmancers install: could not resolve the latest version from npm: ${error.message}\n`);
+        return 1;
+    }
+    io.stdout(`botmancers: installing ${PACKAGE_NAME}@${version} into ${paths.versions} (data under ${paths.home} is left unchanged)\n`);
+    const placed = await withUpdateLock(paths, io, deps, async () => {
+        if (!await stage(paths, env, version, io, deps))
+            return null;
+        const placement = await placeRelease(paths, env, version, io, !flags.to);
+        writeLauncher(paths);
+        return placement;
+    });
+    if (!placed)
+        return 1;
+    pathAdvice(paths, env, io, flags.set.has('--migrate-cli'));
+    if (flags.set.has('--purge-global')) {
+        const result = await (deps.globalNpm ?? runNpm)(['uninstall', '-g', PACKAGE_NAME], env);
+        if (result.code === 0)
+            io.stdout('Removed the npm-global botmancers package.\n');
+        else
+            io.stderr(`botmancers: npm uninstall -g ${PACKAGE_NAME} failed (exit ${result.code}); the managed install is still active.\n`);
+    }
+    io.stdout(`Next: botmancers doctor && botmancers setup && botmancers start --daemon --open\n`);
+    return placed === 'blocked' ? 1 : 0;
+}
+export async function runUpgrade(argv, env, io, deps = {}) {
+    if (argv.includes('-h') || argv.includes('--help')) {
+        io.stdout(UPGRADE_HELP);
+        return 0;
+    }
+    let flags;
+    try {
+        flags = parseFlags(argv, ['--check', '--yes', '-y']);
+    }
+    catch (error) {
+        io.stderr(`botmancers upgrade: ${error.message} Run botmancers upgrade --help.\n`);
+        return 2;
+    }
+    const check = flags.set.has('--check');
+    const install = detectInstallKind(env, { spawnNpm: true });
+    const paths = managedPaths(env);
+    const installed = install.kind === 'managed' ? currentManagedVersion(paths) ?? packageVersion() : packageVersion();
+    let target;
+    try {
+        target = await resolveTarget(env, flags.to, deps);
+    }
+    catch (error) {
+        io.stderr(`botmancers upgrade: could not resolve the latest version from npm: ${error.message}\n`);
+        return 1;
+    }
+    io.stdout(`Install:  ${install.kind} (${install.cliPath})\nCurrent:  ${installed}\n${flags.to ? 'Target' : 'Latest'}:   ${target}\n`);
+    if (install.kind === 'managed') {
+        const pending = readUpdateState(paths).pendingVersion;
+        if (pending && pending !== installed)
+            io.stdout(`Pending:  ${pending} (staged; activates at the next botmancers start)\n`);
+    }
+    const newer = compareSemver(target, installed) > 0;
+    if (!flags.to && !newer) {
+        io.stdout('Already on the latest version.\n');
+        return 0;
+    }
+    if (check) {
+        io.stdout(newer ? `Update available. Run: botmancers upgrade${flags.to ? ` --to ${target}` : ''}\n` : `Run: botmancers upgrade --to ${target}\n`);
+        return 0;
+    }
+    if (install.kind === 'managed') {
+        const placed = await withUpdateLock(paths, io, deps, async () => (await stage(paths, env, target, io, deps) ? placeRelease(paths, env, target, io, true) : null));
+        return !placed || placed === 'blocked' ? 1 : 0;
+    }
+    if (install.kind === 'npm-global') {
+        const command = `npm install -g ${PACKAGE_NAME}@${target}`;
+        const yes = flags.set.has('--yes') || flags.set.has('-y');
+        if (!yes && !await (deps.confirm ?? ttyConfirm)(`Upgrade the npm-global botmancers with "${command}"? [y/N] `)) {
+            io.stdout(`Not upgraded. To upgrade, run: ${command}   (or: botmancers upgrade --yes)\nTip: ${MANAGED_INSTALL_COMMAND}  # managed install with safe auto-updates; data unchanged\n`);
+            return 0;
+        }
+        const result = await (deps.globalNpm ?? runNpm)(['install', '-g', `${PACKAGE_NAME}@${target}`], env);
+        if (result.code !== 0) {
+            io.stderr(`botmancers: ${command} failed (exit ${result.code}): ${result.stderr.trim().split('\n').slice(-3).join(' ')}\n`);
+            return 1;
+        }
+        io.stdout(`Upgraded the npm-global botmancers to ${target}. A running product keeps its version until: ${RESTART_ACTION}\n`);
+        return 0;
+    }
+    const how = install.kind === 'npx' ? `run npx botmancers@${target} instead`
+        : install.kind === 'project-local' ? `run npm install botmancers@${target} in that project`
+            : install.kind === 'dev-checkout' ? 'update the checkout with git and rebuild'
+                : 'reinstall it the way it was installed';
+    io.stderr(`botmancers: this copy is a ${install.kind} install and does not update itself; ${how}.\nRecommended: ${MANAGED_INSTALL_COMMAND}  (managed install with safe auto-updates; data unchanged)\n`);
+    return 1;
+}

package/dist/upstream.js

@@ -1,7 +1,7 @@
 // The Botmancers side of the bridge: JSON-RPC messages POSTed to the app's
 // /api/v0/mcp endpoint with the service token. Failures are classified so
 // the CLI and the MCP surface can say what to fix, without echoing secrets.
-import { MCP_CONTRACT, MCP_PROTOCOL_VERSIONS, loadToolContract } from './contract.js';
+import { MCP_CONTRACT, MCP_CONTRACT_V1, MCP_PROTOCOL_VERSIONS, loadToolContract, toolContractOf } from './contract.js';
 // The serverInfo.name the Botmancers app reports from initialize.
 export const MCP_SERVER_NAME = 'botmancers';
 export const UPSTREAM_PATH = '/api/v0/mcp';
@@ -74,8 +74,10 @@ export function createUpstream(options) {
         return body;
     }
     // initialize and tools/list round trips: authenticate, then confirm the
-    // endpoint is Botmancers and offers every botmancers.mcp.v1 tool. No tool
-    // is called, so preflight writes nothing and is not rate-limited.
+    // endpoint is Botmancers and offers every bundled tool: all of
+    // botmancers.mcp.v1 and all of botmancers.mcp.v2, including the v2
+    // (agent_id) path of botmancers_get_conversation. No tool is called, so
+    // preflight writes nothing and is not rate-limited.
     async function preflight() {
         const incompatible = (why) => new UpstreamError('incompatible', `${options.botmancersUrl}${UPSTREAM_PATH} is an MCP endpoint but not a compatible Botmancers (${why}). Check BOTMANCERS_URL and upgrade Botmancers.`);
         const init = await send({
@@ -95,10 +97,22 @@ export function createUpstream(options) {
         const offered = list.result?.tools;
         if (!Array.isArray(offered))
             throw incompatible('tools/list returned no tools');
-        const names = new Set(offered.map(tool => tool?.name));
-        const missing = loadToolContract().tools.map(tool => tool.name).filter(name => !names.has(name));
-        if (missing.length)
-            throw incompatible(`missing ${MCP_CONTRACT} tools: ${missing.join(', ')}`);
+        const byName = new Map(offered.map(tool => [tool?.name, tool]));
+        const bundled = loadToolContract().tools;
+        const missing = (contract) => bundled.filter(tool => toolContractOf(tool) === contract && !byName.has(tool.name)).map(tool => tool.name);
+        const missingV1 = missing(MCP_CONTRACT_V1);
+        if (missingV1.length)
+            throw incompatible(`missing ${MCP_CONTRACT_V1} tools: ${missingV1.join(', ')}`);
+        const missingV2 = missing(MCP_CONTRACT);
+        const v2Total = bundled.filter(tool => toolContractOf(tool) === MCP_CONTRACT).length;
+        if (missingV2.length === v2Total) {
+            throw incompatible(`it serves only ${MCP_CONTRACT_V1}; this bridge needs ${MCP_CONTRACT} (missing ${missingV2.join(', ')}). Upgrade Botmancers to a release that serves ${MCP_CONTRACT}`);
+        }
+        if (missingV2.length)
+            throw incompatible(`missing ${MCP_CONTRACT} tools: ${missingV2.join(', ')}`);
+        if (!byName.get('botmancers_get_conversation')?.inputSchema?.properties?.agent_id) {
+            throw incompatible(`botmancers_get_conversation lacks the ${MCP_CONTRACT} agent_id path`);
+        }
         const version = result.serverInfo.version;
         return { serverVersion: typeof version === 'string' ? version : null };
     }

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "botmancers",
-  "version": "0.1.0",
-  "description": "Botmancers MCP bridge: a Streamable HTTP MCP server that hands tasks to a Botmancers coordinator (contract botmancers.mcp.v1).",
+  "version": "0.4.2",
+  "description": "Botmancers: the UI, core engine, and authenticated MCP bridge (contracts botmancers.mcp.v1 and botmancers.mcp.v2) as one CLI-managed product. `botmancers start` runs it all; bare `botmancers` runs the bridge only.",
   "keywords": [
     "botmancers",
     "mcp",
     "model-context-protocol",
     "streamable-http",
-    "agents"
+    "agents",
+    "ui",
+    "supervisor"
   ],
   "license": "MIT",
   "author": "Yusuke Muraoka",
@@ -29,6 +31,7 @@
       "default": "./dist/index.js"
     },
     "./schemas/botmancers.mcp.v1.tools.json": "./schemas/botmancers.mcp.v1.tools.json",
+    "./schemas/botmancers.mcp.v2.tools.json": "./schemas/botmancers.mcp.v2.tools.json",
     "./package.json": "./package.json"
   },
   "bin": {
@@ -38,25 +41,29 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "schemas/*.json",
+    "skills/",
+    "app/",
     "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=20"
   },
   "publishConfig": {
-    "access": "public",
-    "provenance": true,
-    "tag": "canary"
+    "access": "public"
   },
   "scripts": {
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc -p tsconfig.json",
+    "build:app": "node scripts/build-app.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && node --test test/",
+    "test": "npm run build && npm run build:app && node --test \"test/*.test.mjs\"",
     "check:pack": "node scripts/check-pack.mjs",
+    "check:skill": "node scripts/check-skill.mjs",
     "smoke:install": "node scripts/smoke-install.mjs",
+    "smoke:product": "node scripts/smoke-product-install.mjs",
+    "smoke:managed": "node scripts/smoke-managed-install.mjs",
     "release:check": "node scripts/release.mjs",
-    "prepack": "npm run build"
+    "prepack": "npm run build && npm run build:app"
   },
   "devDependencies": {
     "@types/node": "20.19.43",