botmancers 0.0.0-stage → 0.3.0

package/app/public/globe.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>

package/app/public/next.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>

package/app/public/vercel.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>

package/app/public/window.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>

package/app/server.js

@@ -0,0 +1,38 @@
+const path = require('path')
+
+const dir = path.join(__dirname)
+
+process.env.NODE_ENV = 'production'
+process.chdir(__dirname)
+
+const currentPort = parseInt(process.env.PORT, 10) || 3000
+const hostname = process.env.HOSTNAME || '0.0.0.0'
+
+let keepAliveTimeout = parseInt(process.env.KEEP_ALIVE_TIMEOUT, 10)
+const nextConfig = {"env":{"BOTMANCERS_BUILD_VERSION":"0.3.0","BOTMANCERS_BUILD_COMMIT":"a08e532e759845e03310017398ab584ebc9d5b9e"},"webpack":null,"typescript":{"ignoreBuildErrors":false},"typedRoutes":false,"distDir":"./.next","cleanDistDir":true,"assetPrefix":"","cacheMaxMemorySize":52428800,"configOrigin":"next.config.ts","useFileSystemPublicRoutes":true,"generateEtags":true,"pageExtensions":["tsx","ts","jsx","js"],"instrumentationClientInject":[],"poweredByHeader":true,"compress":true,"images":{"deviceSizes":[640,750,828,1080,1200,1920,2048,3840],"imageSizes":[32,48,64,96,128,256,384],"path":"/_next/image","loader":"default","loaderFile":"","domains":[],"disableStaticImages":false,"minimumCacheTTL":14400,"formats":["image/webp"],"maximumRedirects":3,"maximumResponseBody":50000000,"dangerouslyAllowLocalIP":false,"dangerouslyAllowSVG":false,"contentSecurityPolicy":"script-src 'none'; frame-src 'none'; sandbox;","contentDispositionType":"attachment","localPatterns":[{"pathname":"**","search":""}],"remotePatterns":[],"qualities":[75],"unoptimized":true,"customCacheHandler":false},"devIndicators":{"position":"bottom-left"},"onDemandEntries":{"maxInactiveAge":60000,"pagesBufferLength":5},"basePath":"","sassOptions":{},"trailingSlash":false,"i18n":null,"productionBrowserSourceMaps":false,"excludeDefaultMomentLocales":true,"reactProductionProfiling":false,"reactStrictMode":null,"reactMaxHeadersLength":6000,"httpAgentOptions":{"keepAlive":true},"logging":{"serverFunctions":true,"browserToTerminal":"warn"},"compiler":{},"expireTime":31536000,"staticPageGenerationTimeout":60,"output":"standalone","modularizeImports":{"@mui/icons-material":{"transform":"@mui/icons-material/{{member}}"},"lodash":{"transform":"lodash/{{member}}"}},"outputFileTracingRoot":__dirname,"enablePrerenderSourceMaps":true,"cacheComponents":false,"cacheLife":{"default":{"stale":300,"revalidate":900,"expire":4294967294},"seconds":{"stale":30,"revalidate":1,"expire":60},"minutes":{"stale":300,"revalidate":60,"expire":3600},"hours":{"stale":300,"revalidate":3600,"expire":86400},"days":{"stale":300,"revalidate":86400,"expire":604800},"weeks":{"stale":300,"revalidate":604800,"expire":2592000},"max":{"stale":300,"revalidate":2592000,"expire":31536000}},"cacheHandlers":{},"experimental":{"appNewScrollHandler":true,"coldCacheBadge":false,"devValidationWorker":true,"useSkewCookie":false,"cssChunking":true,"multiZoneDraftMode":false,"appNavFailHandling":false,"prerenderEarlyExit":true,"serverMinification":true,"linkNoTouchStart":false,"caseSensitiveRoutes":false,"cachedNavigations":false,"dynamicOnHover":false,"useOffline":false,"varyParams":true,"optimisticRouting":true,"instrumentationClientRouterTransitionEvents":false,"prefetchInlining":{"maxSize":2048,"maxBundleSize":10240},"preloadEntriesOnStart":true,"clientRouterFilter":true,"clientRouterFilterRedirects":false,"fetchCacheKeyPrefix":"","proxyPrefetch":"flexible","optimisticClientCache":true,"manualClientBasePath":false,"cpus":9,"memoryBasedWorkersCount":false,"imgOptConcurrency":null,"imgOptOperationCache":null,"imgOptTimeoutInSeconds":7,"imgOptMaxInputPixels":268402689,"imgOptSequentialRead":null,"isrFlushToDisk":true,"workerThreads":false,"optimizeCss":false,"nextScriptWorkers":false,"scrollRestoration":false,"externalDir":false,"devMemoryThresholdRestart":true,"disableOptimizedLoading":false,"gzipSize":true,"craCompat":false,"esmExternals":true,"fullySpecified":false,"swcTraceProfiling":false,"forceSwcTransforms":false,"requestInsights":false,"largePageDataBytes":128000,"typedEnv":false,"parallelServerCompiles":false,"parallelServerBuildTraces":false,"ppr":false,"authInterrupts":false,"webpackMemoryOptimizations":false,"optimizeServerReact":true,"strictRouteTypes":false,"useTypeScriptCli":true,"removeUncaughtErrorAndRejectionListeners":false,"validateRSCRequestHeaders":true,"staleTimes":{"dynamic":0,"static":300},"reactDebugChannel":true,"serverComponentsHmrCache":true,"serverComponentsHmrCancellation":false,"staticGenerationMaxConcurrency":8,"staticGenerationMinPagesPerWorker":25,"transitionIndicator":false,"gestureTransition":false,"inlineCss":false,"useCache":false,"globalNotFound":false,"browserDebugInfoInTerminal":"warn","lockDistDir":true,"proxyClientMaxBodySize":10485760,"hideLogsAfterAbort":false,"mcpServer":true,"turbopackFileSystemCacheForDev":true,"turbopackFileSystemCacheForBuild":true,"turbopackInferModuleSideEffects":true,"turbopackPluginRuntimeStrategy":"childProcesses","turbopackMemoryEvictionMode":"auto","optimizePackageImports":["lucide-react","date-fns","lodash-es","ramda","antd","react-bootstrap","ahooks","@ant-design/icons","@headlessui/react","@headlessui-float/react","@heroicons/react/20/solid","@heroicons/react/24/solid","@heroicons/react/24/outline","@visx/visx","@tremor/react","rxjs","@mui/material","@mui/icons-material","recharts","react-use","effect","@effect/schema","@effect/platform","@effect/platform-node","@effect/platform-browser","@effect/platform-bun","@effect/sql","@effect/sql-mssql","@effect/sql-mysql2","@effect/sql-pg","@effect/sql-sqlite-node","@effect/sql-sqlite-bun","@effect/sql-sqlite-wasm","@effect/sql-sqlite-react-native","@effect/rpc","@effect/rpc-http","@effect/typeclass","@effect/experimental","@effect/opentelemetry","@material-ui/core","@material-ui/icons","@tabler/icons-react","mui-core","react-icons/ai","react-icons/bi","react-icons/bs","react-icons/cg","react-icons/ci","react-icons/di","react-icons/fa","react-icons/fa6","react-icons/fc","react-icons/fi","react-icons/gi","react-icons/go","react-icons/gr","react-icons/hi","react-icons/hi2","react-icons/im","react-icons/io","react-icons/io5","react-icons/lia","react-icons/lib","react-icons/lu","react-icons/md","react-icons/pi","react-icons/ri","react-icons/rx","react-icons/si","react-icons/sl","react-icons/tb","react-icons/tfi","react-icons/ti","react-icons/vsc","react-icons/wi"],"useCacheTimeout":54,"instantInsights":{"validationLevel":"warning"},"trustHostHeader":false,"isExperimentalCompile":false},"htmlLimitedBots":"[\\w-]+-Google|Google-[\\w-]+|Chrome-Lighthouse|Slurp|DuckDuckBot|baiduspider|yandex|sogou|bitlybot|tumblr|vkShare|quora link preview|redditbot|ia_archiver|Bingbot|BingPreview|applebot|facebookexternalhit|facebookcatalog|Twitterbot|LinkedInBot|Slackbot|Discordbot|WhatsApp|SkypeUriPreview|Yeti|googleweblight","bundlePagesRouterDependencies":false,"configFileName":"next.config.ts","repoRoot":__dirname,"turbopack":{"root":__dirname},"distDirRoot":".next","_originalRewrites":{"beforeFiles":[],"afterFiles":[{"source":"/favicon.ico","destination":"/brand/botmancers-logo-filled-64.png"}],"fallback":[]}}
+
+process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = JSON.stringify(nextConfig)
+
+require('next')
+const { startServer } = require('next/dist/server/lib/start-server')
+
+if (
+  Number.isNaN(keepAliveTimeout) ||
+  !Number.isFinite(keepAliveTimeout) ||
+  keepAliveTimeout < 0
+) {
+  keepAliveTimeout = undefined
+}
+
+startServer({
+  dir,
+  isDev: false,
+  config: nextConfig,
+  hostname,
+  port: currentPort,
+  allowRetry: false,
+  keepAliveTimeout,
+}).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/cli.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly config: 2;
+    readonly listen: 3;
+    readonly unavailable: 4;
+    readonly credentials: 5;
+};
+export interface CliIo {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+}
+export declare const PRODUCT_COMMANDS: readonly ["setup", "start", "stop", "status", "doctor", "open"];
+export declare const INSTALL_COMMANDS: readonly ["install", "upgrade"];
+export declare const UPDATE_WORKER_COMMAND = "__update-check";
+export declare const PRODUCT_HELP = "Usage: botmancers <command>\n\nRun Botmancers (UI, API, core engine, and MCP bridge) from this package:\n\n  setup                     Create BOTMANCERS_HOME (owner-only) and generate the\n                            bridge credentials; prints Hermes and Agent Deck steps\n  start [--daemon] [--open] Start the UI/core on 127.0.0.1:43123 and the MCP bridge\n                            on 127.0.0.1:43124 under one supervisor\n  stop                      Stop the supervisor, core, and bridge\n  status                    Report healthy / degraded / stopped, versions, endpoints\n  doctor                    Check the installation, home, ports, Hermes, Agent Deck\n  open                      Open the UI in a browser\n  mcp [options]             Run only the MCP bridge (same as bare `botmancers`)\n  install [--to VERSION]    Managed install into ~/.botmancers/versions with the\n                            ~/.local/bin/botmancers launcher (--help for options)\n  upgrade [--check] [--to VERSION] [--yes]\n                            Update this installation (managed or npm-global)\n\nManaged installs update themselves: at most one npm check a day, a background\ndownload, activation at the next `botmancers start` once nothing is running.\nBOTMANCERS_DISABLE_AUTOUPDATER=1 turns that off; `botmancers upgrade` still works.\n\nEnvironment: BOTMANCERS_HOME (default ~/.botmancers), BOTMANCERS_UI_PORT,\nBOTMANCERS_MCP_PORT. Variables exported in your shell (HERMES_*, BOTMANCERS_DB_PATH,\n...) take precedence over <home>/config/core.env.\n\nExit codes: 0 ok, 1 degraded or check failed, 2 usage, 3 not running,\n6 port in use, 7 core or bridge failed to start, 8 packaged app incomplete,\n9 home not writable, 10 not set up (run botmancers setup).\n";
+export declare function productMain(command: typeof PRODUCT_COMMANDS[number], argv: string[], env: NodeJS.ProcessEnv, io?: CliIo): Promise<number>;
+export declare function main(argv: string[], env: NodeJS.ProcessEnv, io?: CliIo): Promise<number | 'serving'>;
+export declare function bridgeMain(argv: string[], env: NodeJS.ProcessEnv, io?: CliIo): Promise<number | 'serving'>;

package/dist/cli.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+// The `botmancers` command.
+//
+//   botmancers [options]        the MCP bridge only (unchanged since 0.1.0)
+//   botmancers mcp [options]    the same, explicitly
+//   botmancers setup|start|stop|status|doctor|open
+//                               the full product: UI, API, core engine, and
+//                               bridge under one supervisor (./product)
+//   botmancers install|upgrade  the managed install and its updates (./upgrade)
+//
+// Bridge mode: validate configuration, check that Botmancers is reachable
+// and accepts the service token, then serve the MCP bridge until a signal.
+import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { ConfigError, ENV, HELP, isLoopbackHost, parseCli } from './config.js';
+import { packageVersion } from './contract.js';
+import { createRedactor } from './redact.js';
+import { HEALTH_PATH, MCP_PATH, createBridge } from './server.js';
+import { UpstreamError } from './upstream.js';
+import { PRODUCT_EXIT, UsageError, doctor, open, parseStartArgs, productContext, start, status, stop } from './product.js';
+import { SetupError, runSetup } from './setup.js';
+import { DISABLE_AUTOUPDATER_ENV, runUpdateCheck, scheduleAutoUpdate } from './managed.js';
+import { runInstall, runUpgrade } from './upgrade.js';
+export const EXIT = { ok: 0, config: 2, listen: 3, unavailable: 4, credentials: 5 };
+const processIo = {
+    stdout: text => process.stdout.write(text),
+    stderr: text => process.stderr.write(text),
+};
+function urlHost(url) {
+    return new URL(url).hostname;
+}
+export const PRODUCT_COMMANDS = ['setup', 'start', 'stop', 'status', 'doctor', 'open'];
+export const INSTALL_COMMANDS = ['install', 'upgrade'];
+// The detached auto-update worker (./managed scheduleAutoUpdate); not for people.
+export const UPDATE_WORKER_COMMAND = '__update-check';
+export const PRODUCT_HELP = `Usage: botmancers <command>
+
+Run Botmancers (UI, API, core engine, and MCP bridge) from this package:
+
+  setup                     Create BOTMANCERS_HOME (owner-only) and generate the
+                            bridge credentials; prints Hermes and Agent Deck steps
+  start [--daemon] [--open] Start the UI/core on 127.0.0.1:43123 and the MCP bridge
+                            on 127.0.0.1:43124 under one supervisor
+  stop                      Stop the supervisor, core, and bridge
+  status                    Report healthy / degraded / stopped, versions, endpoints
+  doctor                    Check the installation, home, ports, Hermes, Agent Deck
+  open                      Open the UI in a browser
+  mcp [options]             Run only the MCP bridge (same as bare \`botmancers\`)
+  install [--to VERSION]    Managed install into ~/.botmancers/versions with the
+                            ~/.local/bin/botmancers launcher (--help for options)
+  upgrade [--check] [--to VERSION] [--yes]
+                            Update this installation (managed or npm-global)
+
+Managed installs update themselves: at most one npm check a day, a background
+download, activation at the next \`botmancers start\` once nothing is running.
+${DISABLE_AUTOUPDATER_ENV}=1 turns that off; \`botmancers upgrade\` still works.
+
+Environment: BOTMANCERS_HOME (default ~/.botmancers), BOTMANCERS_UI_PORT,
+BOTMANCERS_MCP_PORT. Variables exported in your shell (HERMES_*, BOTMANCERS_DB_PATH,
+...) take precedence over <home>/config/core.env.
+
+Exit codes: 0 ok, 1 degraded or check failed, 2 usage, 3 not running,
+6 port in use, 7 core or bridge failed to start, 8 packaged app incomplete,
+9 home not writable, 10 not set up (run botmancers setup).
+`;
+// Product commands (./product). Resolves when the command finishes; a
+// foreground `start` resolves only after the product stops.
+export async function productMain(command, argv, env, io = processIo) {
+    if (argv.includes('-h') || argv.includes('--help')) {
+        io.stdout(PRODUCT_HELP);
+        return PRODUCT_EXIT.ok;
+    }
+    try {
+        const ctx = productContext(env, io);
+        // The running supervisor schedules its own checks; `start` reaches it.
+        if (command !== 'start')
+            scheduleAutoUpdate(env);
+        if (command !== 'start' && argv.length)
+            throw new UsageError(`${command} takes no arguments.`);
+        switch (command) {
+            case 'setup': {
+                const result = runSetup(ctx.paths, { ui: ctx.uiPort, mcp: ctx.mcpPort });
+                ctx.io.stdout(`${result.lines.join('\n')}\n`);
+                return PRODUCT_EXIT.ok;
+            }
+            case 'start': return await start(ctx, parseStartArgs(argv));
+            case 'stop': return await stop(ctx);
+            case 'status': return await status(ctx);
+            case 'doctor': return await doctor(ctx);
+            case 'open': return await open(ctx);
+        }
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            io.stderr(`botmancers ${command}: ${error.message} Run botmancers ${command} --help.\n`);
+            return PRODUCT_EXIT.usage;
+        }
+        if (error instanceof SetupError) {
+            io.stderr(`botmancers setup: ${error.message}\n`);
+            return PRODUCT_EXIT.home;
+        }
+        throw error;
+    }
+}
+// Routes product commands and `mcp`; anything else is bridge mode, exactly
+// as before the product commands existed.
+export async function main(argv, env, io = processIo) {
+    const [first, ...rest] = argv;
+    if (first === 'mcp')
+        return bridgeMain(rest, env, io);
+    if (first === 'install')
+        return runInstall(rest, env, io);
+    if (first === 'upgrade')
+        return runUpgrade(rest, env, io);
+    if (first === UPDATE_WORKER_COMMAND) {
+        await runUpdateCheck(env);
+        return EXIT.ok;
+    }
+    if (PRODUCT_COMMANDS.includes(first))
+        return productMain(first, rest, env, io);
+    return bridgeMain(argv, env, io);
+}
+export async function bridgeMain(argv, env, io = processIo) {
+    // Redact whatever secrets the environment holds before anything is printed.
+    const redact = createRedactor([env[ENV.serviceToken]?.trim(), env[ENV.mcpToken]?.trim()]);
+    const err = (line) => io.stderr(`${redact(line)}\n`);
+    let command;
+    try {
+        command = parseCli(argv, env);
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError))
+            throw error;
+        err('botmancers: configuration error:');
+        for (const problem of error.problems)
+            err(`  - ${problem}`);
+        err('Run botmancers --help for all options.');
+        return EXIT.config;
+    }
+    if (command.kind === 'help') {
+        io.stdout(HELP);
+        return EXIT.ok;
+    }
+    if (command.kind === 'version') {
+        io.stdout(`${packageVersion()}\n`);
+        return EXIT.ok;
+    }
+    const { config } = command;
+    const bridge = createBridge({ config, logger: { info: err, error: err } });
+    if (!isLoopbackHost(config.host)) {
+        err(`botmancers: warning: binding ${config.host}, not loopback. Expose the bridge only on a private network or behind an HTTPS (TLS-terminating) proxy.`);
+    }
+    if (config.botmancersUrl.startsWith('http://') && !isLoopbackHost(urlHost(config.botmancersUrl))) {
+        err(`botmancers: warning: ${ENV.url} uses plain http:// to a non-loopback host; the service token is sent unencrypted. Use https://.`);
+    }
+    try {
+        await bridge.upstream.preflight();
+    }
+    catch (error) {
+        if (!(error instanceof UpstreamError))
+            throw error;
+        err(`botmancers: ${error.message}`);
+        return error.kind === 'unauthorized' || error.kind === 'unconfigured' ? EXIT.credentials : EXIT.unavailable;
+    }
+    let address;
+    try {
+        address = await bridge.listen();
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'EADDRINUSE') {
+            err(`botmancers: port ${config.port} on ${config.host} is already in use. Stop the other process or choose another port with --port or ${ENV.port}.`);
+        }
+        else if (code === 'EADDRNOTAVAIL') {
+            err(`botmancers: cannot bind ${config.host}: no such local address. Check --host or ${ENV.host}.`);
+        }
+        else if (code === 'EACCES') {
+            err(`botmancers: permission denied binding ${config.host}:${config.port}. Use a port above 1023.`);
+        }
+        else {
+            err(`botmancers: cannot listen on ${config.host}:${config.port} (${code ?? error.message}).`);
+        }
+        return EXIT.listen;
+    }
+    const shown = address.family === 'IPv6' ? `[${address.address}]` : address.address;
+    err(`botmancers ${packageVersion()}: MCP bridge listening on http://${shown}:${address.port}${MCP_PATH} (health: ${HEALTH_PATH}) -> ${config.botmancersUrl}`);
+    const stop = (signal) => {
+        err(`botmancers: ${signal} received, shutting down.`);
+        bridge.close().then(() => process.exit(EXIT.ok));
+    };
+    process.once('SIGINT', () => stop('SIGINT'));
+    process.once('SIGTERM', () => stop('SIGTERM'));
+    return 'serving';
+}
+function invokedDirectly() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedDirectly()) {
+    main(process.argv.slice(2), process.env).then(outcome => {
+        if (outcome !== 'serving') {
+            process.exitCode = outcome;
+            // A finished product command must not linger on open handles.
+            if (process.argv[2] && [...PRODUCT_COMMANDS, ...INSTALL_COMMANDS, UPDATE_WORKER_COMMAND].includes(process.argv[2]))
+                process.exit(outcome);
+        }
+    }, error => {
+        const redact = createRedactor([process.env[ENV.serviceToken]?.trim(), process.env[ENV.mcpToken]?.trim()]);
+        process.stderr.write(`botmancers: unexpected error: ${redact(error?.message ?? String(error))}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+export declare const ENV: {
+    readonly url: "BOTMANCERS_URL";
+    readonly serviceToken: "BOTMANCERS_SERVICE_TOKEN";
+    readonly mcpToken: "BOTMANCERS_MCP_TOKEN";
+    readonly host: "BOTMANCERS_MCP_HOST";
+    readonly port: "BOTMANCERS_MCP_PORT";
+};
+export declare const DEFAULT_HOST = "127.0.0.1";
+export declare const DEFAULT_PORT = 43124;
+export declare const MIN_MCP_TOKEN_LENGTH = 16;
+export interface BridgeConfig {
+    botmancersUrl: string;
+    serviceToken: string;
+    mcpToken: string;
+    host: string;
+    port: number;
+}
+export type CliCommand = {
+    kind: 'help';
+} | {
+    kind: 'version';
+} | {
+    kind: 'serve';
+    config: BridgeConfig;
+};
+export declare class ConfigError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+export declare function isLoopbackHost(host: string): boolean;
+export declare function parseBotmancersUrl(raw: string): {
+    url?: string;
+    problem?: string;
+};
+export declare function parseCli(argv: string[], env: NodeJS.ProcessEnv): CliCommand;
+export declare const HELP: string;

package/dist/config.js

@@ -0,0 +1,192 @@
+// Bridge configuration: environment variables, with command-line flags for
+// the non-secret settings. Secrets are accepted only from the environment
+// (flags are visible to every local user through the process list).
+import { isIP } from 'node:net';
+export const ENV = {
+    url: 'BOTMANCERS_URL',
+    serviceToken: 'BOTMANCERS_SERVICE_TOKEN',
+    mcpToken: 'BOTMANCERS_MCP_TOKEN',
+    host: 'BOTMANCERS_MCP_HOST',
+    port: 'BOTMANCERS_MCP_PORT',
+};
+export const DEFAULT_HOST = '127.0.0.1';
+export const DEFAULT_PORT = 43124;
+export const MIN_MCP_TOKEN_LENGTH = 16;
+export class ConfigError extends Error {
+    problems;
+    constructor(problems) {
+        super(problems.join('\n'));
+        this.name = 'ConfigError';
+        this.problems = problems;
+    }
+}
+const FLAGS = {
+    '--botmancers-url': 'url',
+    '--host': 'host',
+    '--port': 'port',
+};
+const SECRET_FLAGS = ['--service-token', '--mcp-token', '--token'];
+export function isLoopbackHost(host) {
+    const bare = host.replace(/^\[|\]$/g, '').toLowerCase();
+    return bare === 'localhost' || bare === '::1' || /^127(?:\.\d{1,3}){3}$/.test(bare);
+}
+function validToken(value) {
+    return /^[\x21-\x7e]+$/.test(value) && value.length <= 4096;
+}
+export function parseBotmancersUrl(raw) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        // Never echo the value: an operator may have pasted a token into it.
+        return { problem: `${ENV.url} is not a valid absolute URL. Expected something like http://127.0.0.1:43123.` };
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return { problem: `${ENV.url} must use http:// or https:// (got ${parsed.protocol}//).` };
+    }
+    if (parsed.username || parsed.password) {
+        return { problem: `${ENV.url} must not contain credentials; put the service token in ${ENV.serviceToken} instead.` };
+    }
+    if (parsed.search || parsed.hash) {
+        return { problem: `${ENV.url} must not contain a query string or fragment.` };
+    }
+    return { url: `${parsed.origin}${parsed.pathname.replace(/\/+$/, '')}` };
+}
+function parsePort(raw, source) {
+    const trimmed = raw.trim();
+    const port = /^\d+$/.test(trimmed) ? Number(trimmed) : NaN;
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        // Never echo the value: a token pasted into the wrong setting must not be printed.
+        return { problem: `${source} must be an integer port between 0 and 65535 (default ${DEFAULT_PORT}, 0 for any free port).` };
+    }
+    return { port };
+}
+function parseHost(raw, source) {
+    const host = raw.trim();
+    if (isIP(host.replace(/^\[|\]$/g, '')) || /^[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?$/.test(host)) {
+        return { host: host.replace(/^\[|\]$/g, '') };
+    }
+    return { problem: `${source} must be an IP address or hostname to bind (default ${DEFAULT_HOST}).` };
+}
+// Parses argv (without node and script) and env into a command. Throws
+// ConfigError listing every problem, none of which contains a secret.
+export function parseCli(argv, env) {
+    const fromFlags = {};
+    const problems = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h' || arg === '--help')
+            return { kind: 'help' };
+        if (arg === '-v' || arg === '--version')
+            return { kind: 'version' };
+        const eq = arg.indexOf('=');
+        const name = eq > 0 ? arg.slice(0, eq) : arg;
+        if (SECRET_FLAGS.includes(name)) {
+            problems.push(`${name} is not accepted: pass secrets only through ${ENV.serviceToken} and ${ENV.mcpToken} environment variables.`);
+            if (eq < 0)
+                i++;
+            continue;
+        }
+        const key = FLAGS[name];
+        if (!key) {
+            // Echo only flag-shaped names; a stray positional value may be a pasted token.
+            problems.push(/^--?[a-z][a-z0-9-]{0,38}$/.test(name)
+                ? `Unknown argument ${JSON.stringify(name)}. Run botmancers --help for usage.`
+                : 'Unexpected positional argument (value not shown). Run botmancers --help for usage.');
+            continue;
+        }
+        const value = eq > 0 ? arg.slice(eq + 1) : argv[++i];
+        if (value === undefined || value === '') {
+            problems.push(`${name} needs a value.`);
+            continue;
+        }
+        fromFlags[key] = value;
+    }
+    const pick = (key) => {
+        const value = fromFlags[key] ?? env[ENV[key]];
+        return value === undefined || value.trim() === '' ? undefined : value.trim();
+    };
+    const rawUrl = pick('url');
+    let botmancersUrl = '';
+    if (!rawUrl) {
+        problems.push(`${ENV.url} is required: the Botmancers base URL, for example http://127.0.0.1:43123 (or pass --botmancers-url).`);
+    }
+    else {
+        const { url, problem } = parseBotmancersUrl(rawUrl);
+        if (problem)
+            problems.push(problem);
+        else
+            botmancersUrl = url;
+    }
+    const serviceToken = env[ENV.serviceToken]?.trim() ?? '';
+    if (!serviceToken) {
+        problems.push(`${ENV.serviceToken} is required: the bearer token whose SHA-256 digest Botmancers lists in BOTMANCERS_SERVICE_TOKENS.`);
+    }
+    else if (!validToken(serviceToken)) {
+        problems.push(`${ENV.serviceToken} must be a single printable token without spaces.`);
+    }
+    const mcpToken = env[ENV.mcpToken]?.trim() ?? '';
+    if (!mcpToken) {
+        problems.push(`${ENV.mcpToken} is required: the bearer token MCP clients must send to this bridge (generate one with: openssl rand -hex 32).`);
+    }
+    else if (!validToken(mcpToken) || mcpToken.length < MIN_MCP_TOKEN_LENGTH) {
+        problems.push(`${ENV.mcpToken} must be a single printable token of at least ${MIN_MCP_TOKEN_LENGTH} characters without spaces.`);
+    }
+    else if (mcpToken === serviceToken) {
+        problems.push(`${ENV.mcpToken} must differ from ${ENV.serviceToken}: MCP clients must not hold the Botmancers service token.`);
+    }
+    let host = DEFAULT_HOST;
+    const rawHost = pick('host');
+    if (rawHost) {
+        const parsed = parseHost(rawHost, fromFlags.host ? '--host' : ENV.host);
+        if (parsed.problem)
+            problems.push(parsed.problem);
+        else
+            host = parsed.host;
+    }
+    let port = DEFAULT_PORT;
+    const rawPort = pick('port');
+    if (rawPort) {
+        const parsed = parsePort(rawPort, fromFlags.port ? '--port' : ENV.port);
+        if (parsed.problem)
+            problems.push(parsed.problem);
+        else
+            port = parsed.port;
+    }
+    if (problems.length)
+        throw new ConfigError(problems);
+    return { kind: 'serve', config: { botmancersUrl, serviceToken, mcpToken, host, port } };
+}
+export const HELP = `Usage: botmancers [options]
+
+Run the Botmancers MCP bridge: a Streamable HTTP MCP server (contract
+botmancers.mcp.v1) that forwards tool calls to a running Botmancers app.
+
+Options:
+  --botmancers-url <url>  Botmancers base URL            (env ${ENV.url}, required)
+  --host <host>           Address to bind                (env ${ENV.host}, default ${DEFAULT_HOST})
+  --port <port>           Port to bind, 0 for any free   (env ${ENV.port}, default ${DEFAULT_PORT})
+  -h, --help              Show this help
+  -v, --version           Show the package version
+
+Secrets (environment only, never flags):
+  ${ENV.serviceToken}   Bearer token this bridge sends to Botmancers (required)
+  ${ENV.mcpToken}       Bearer token MCP clients must send to this bridge (required, >= ${MIN_MCP_TOKEN_LENGTH} chars)
+
+Endpoints:
+  POST /mcp       MCP Streamable HTTP (Authorization: Bearer $${ENV.mcpToken})
+  GET  /healthz   Liveness (no authentication, no upstream call)
+
+Example:
+  ${ENV.url}=http://127.0.0.1:43123 \\
+  ${ENV.serviceToken}=... ${ENV.mcpToken}=$(openssl rand -hex 32) \\
+  npx botmancers
+
+Exit codes: 0 stopped by signal, 2 configuration, 3 cannot listen,
+4 Botmancers unreachable or incompatible, 5 credentials rejected.
+
+\`botmancers mcp [options]\` is the same bridge-only command. To run the whole
+product (UI, API, core engine, and this bridge) instead:
+  botmancers setup && botmancers start --daemon     (see: botmancers start --help)
+`;

package/dist/contract.d.ts

@@ -0,0 +1,21 @@
+export declare const MCP_CONTRACT = "botmancers.mcp.v1";
+export declare const MCP_PROTOCOL_VERSIONS: readonly ["2025-11-25", "2025-06-18", "2025-03-26"];
+export declare const MCP_INSTRUCTIONS: string;
+export interface McpTool {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+}
+export interface ToolContract {
+    contract: string;
+    tools: McpTool[];
+}
+export declare const TOOL_SCHEMA_URL: import("url").URL;
+export declare function loadToolContract(): ToolContract;
+export declare function negotiateProtocolVersion(requested: unknown): string;
+export declare const PACKAGE_JSON_URL: import("url").URL;
+export declare function packageVersion(): string;

package/dist/contract.js

@@ -0,0 +1,28 @@
+// The botmancers.mcp.v1 tool contract, as captured by the Botmancers app in
+// docs/contracts/mcp-bridge-v1.tools.json and shipped here as a versioned
+// schema file. The bridge serves tools/list from it and forwards only these
+// tool names to Botmancers; it never alters the contract.
+import { readFileSync } from 'node:fs';
+export const MCP_CONTRACT = 'botmancers.mcp.v1';
+// Newest first; an unknown client version is answered with the newest.
+// Same list as the Botmancers app's /api/v0/mcp endpoint.
+export const MCP_PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26'];
+export const MCP_INSTRUCTIONS = 'Botmancers bridge (botmancers.mcp.v1). Start a task with botmancers_start_task, then poll botmancers_get_request '
+    + 'until terminal and read botmancers_get_conversation; it stays active while the coordinator\'s follow-up work is open.';
+export const TOOL_SCHEMA_URL = new URL('../schemas/botmancers.mcp.v1.tools.json', import.meta.url);
+export function loadToolContract() {
+    const parsed = JSON.parse(readFileSync(TOOL_SCHEMA_URL, 'utf8'));
+    if (parsed.contract !== MCP_CONTRACT || !Array.isArray(parsed.tools)) {
+        throw new Error(`The bundled tool schema is not ${MCP_CONTRACT}; reinstall the botmancers package.`);
+    }
+    return parsed;
+}
+export function negotiateProtocolVersion(requested) {
+    return typeof requested === 'string' && MCP_PROTOCOL_VERSIONS.includes(requested)
+        ? requested
+        : MCP_PROTOCOL_VERSIONS[0];
+}
+export const PACKAGE_JSON_URL = new URL('../package.json', import.meta.url);
+export function packageVersion() {
+    return JSON.parse(readFileSync(PACKAGE_JSON_URL, 'utf8')).version;
+}

package/dist/home.d.ts

@@ -0,0 +1,39 @@
+export declare const HOME_ENV = "BOTMANCERS_HOME";
+export declare const APP_DIR_ENV = "BOTMANCERS_APP_DIR";
+export declare const UI_PORT_ENV = "BOTMANCERS_UI_PORT";
+export declare const DEFAULT_UI_PORT = 43123;
+export declare const PRODUCT_HOST = "127.0.0.1";
+export declare const HOME_DIRS: readonly ["config", "data", "files", "skills", "logs", "run"];
+export interface HomePaths {
+    home: string;
+    config: string;
+    coreEnv: string;
+    bridgeEnv: string;
+    data: string;
+    db: string;
+    files: string;
+    skills: string;
+    logs: string;
+    supervisorLog: string;
+    uiLog: string;
+    mcpLog: string;
+    run: string;
+    runFile: string;
+}
+export declare function resolveHome(env: NodeJS.ProcessEnv): string;
+export declare function homePaths(home: string): HomePaths;
+export declare function appDir(env: NodeJS.ProcessEnv): string;
+export declare const CLI_PATH: string;
+export declare const REQUIRED_APP_FILES: readonly ["server.js", "package.json", "BUILD_INFO.json", ".next/BUILD_ID", ".next/static", "public", "node_modules/next/package.json", "node_modules/better-sqlite3/package.json"];
+export declare function missingAppFiles(dir: string): string[];
+export interface BuildInfo {
+    version: string;
+    commit: string;
+}
+export declare function readBuildInfo(dir: string): BuildInfo | null;
+export declare function parseEnvFile(text: string): Record<string, string>;
+export declare function readEnvFile(path: string): Record<string, string> | null;
+export declare function writePrivateFile(path: string, text: string): void;
+export declare function ensurePrivateDir(path: string): void;
+export declare function modeOf(path: string): number | null;
+export declare function portFrom(env: NodeJS.ProcessEnv, name: string, fallback: number): number;