@swarmclawai/swarmclaw 0.7.3 → 0.7.4

package/README.md

@@ -37,6 +37,8 @@ SwarmClaw was built for OpenClaw users who outgrew a single agent. Connect each
 
 SwarmClaw includes the `openclaw` CLI as a bundled dependency, so there is no separate OpenClaw CLI install step.
 
+The Providers screen now supports named OpenClaw gateway profiles with discovery, health checks, default-gateway selection, and an External Agent Runtimes view for remote workers that register/heartbeat into SwarmClaw.
+
 The OpenClaw Control Plane in SwarmClaw adds:
 - Reload mode switching (`hot`, `hybrid`, `full`)
 - Config issue detection and guided repair
@@ -47,13 +49,13 @@ The Agent Inspector Panel lets you edit OpenClaw files (`SOUL.md`, `IDENTITY.md`
 
 To connect an agent to an OpenClaw gateway:
 
-1. Create or edit an agent
-2. Toggle **OpenClaw Gateway** ON
-3. Enter the gateway URL (e.g. `http://192.168.1.50:18789` or `https://my-vps:18789`)
-4. Add a gateway token if authentication is enabled on the remote gateway
+1. Optional: create a named gateway profile in **Providers** and mark a default
+2. Create or edit an agent
+3. Toggle **OpenClaw Gateway** ON
+4. Select a saved gateway profile or enter a direct gateway URL/token override
 5. Click **Connect** — approve the device in your gateway's dashboard if prompted, then **Retry Connection**
 
-Each agent can point to a **different** OpenClaw gateway — one local, several remote. This is how you manage a **swarm of OpenClaws** from a single dashboard.
+Each agent can point to a **different** OpenClaw gateway profile or direct endpoint — one local, several remote. This is how you manage a **swarm of OpenClaws** from a single dashboard.
 
 URLs without a protocol are auto-prefixed with `http://`. For remote gateways with TLS, use `https://` explicitly.
 
@@ -77,21 +79,37 @@ Skill source and runbook: [`swarmclaw/SKILL.md`](swarmclaw/SKILL.md).
 ## Requirements
 
 - **Node.js** 22.6+
-- **npm** 10+
+- **Node.js** 22.6+
+- One of: **npm** 10+, **pnpm**, **Yarn**, or **Bun**
 - **Claude Code CLI** (optional, for `claude-cli` provider) — [Install](https://docs.anthropic.com/en/docs/claude-code/overview)
 - **OpenAI Codex CLI** (optional, for `codex-cli` provider) — [Install](https://github.com/openai/codex)
 - **OpenCode CLI** (optional, for `opencode-cli` provider) — [Install](https://github.com/opencode-ai/opencode)
 - **Gemini CLI** (optional, for `delegate` backend `gemini`) — install and authenticate `gemini` on your host
+- **Deno** (required for `sandbox_exec`) — auto-installed by `npm run quickstart` / `npm run setup:easy` when missing
 
 ## Quick Start
 
-### npm (recommended)
+SwarmClaw is published to the npm registry once and can be installed with `npm`, `pnpm`, `yarn`, or `bun`. There is no separate package-manager signup for end users.
+
+### Global install
 
 ```bash
 npm i -g @swarmclawai/swarmclaw
+pnpm add -g @swarmclawai/swarmclaw
+yarn global add @swarmclawai/swarmclaw
+bun add -g @swarmclawai/swarmclaw
 swarmclaw
 ```
 
+### One-off run
+
+```bash
+npx @swarmclawai/swarmclaw
+pnpm dlx @swarmclawai/swarmclaw
+yarn dlx @swarmclawai/swarmclaw
+bunx @swarmclawai/swarmclaw
+```
+
 ### Install script
 
 ```bash
@@ -99,7 +117,7 @@ curl -fsSL https://raw.githubusercontent.com/swarmclawai/swarmclaw/main/install.
 ```
 
 The installer resolves the latest stable release tag and installs that version by default.
-To pin a version: `SWARMCLAW_VERSION=v0.7.3 curl ... | bash`
+To pin a version: `SWARMCLAW_VERSION=v0.7.4 curl ... | bash`
 
 Or run locally from the repo (friendly for non-technical users):
 
@@ -111,10 +129,19 @@ npm run quickstart
 
 `npm run quickstart` will:
 - Check Node/npm versions
+- Install Deno if the sandbox runtime is missing
 - Install dependencies
 - Prepare `.env.local` and `data/`
 - Start the app at `http://localhost:3456`
 
+If you prefer another package manager for local development:
+
+```bash
+pnpm install && pnpm dev
+yarn install && yarn dev
+bun install && bun run dev
+```
+
 `postinstall` rebuilds `better-sqlite3` natively. If you install with `--ignore-scripts`, run `npm rebuild better-sqlite3` manually.
 
 On first launch, SwarmClaw will:
@@ -143,7 +170,7 @@ Notes:
 - When run with no flags in a TTY, `setup init` enters interactive mode — pick providers, enter keys, name agents, and add multiple providers in one session.
 - Use `--no-interactive` to force flag-only mode.
 - On a fresh instance, `setup init` can auto-discover and claim the first-run access key from `/api/auth`.
-- For existing installs, pass `--key <ACCESS_KEY>` (or set `SWARMCLAW_ACCESS_KEY`).
+- For existing installs, pass `--key <ACCESS_KEY>` or set `SWARMCLAW_ACCESS_KEY` / `SWARMCLAW_API_KEY`.
 - `setup init` performs provider validation, stores credentials, creates a starter agent, and marks setup complete.
 - Use `--skip-check` to bypass connection validation.
 
@@ -164,7 +191,7 @@ Notes:
 ## Features
 
 - **15 providers out of the box** - CLI providers + major hosted APIs + OpenAI-compatible custom endpoints
-- **OpenClaw-native control plane** - per-agent gateway mapping, reload modes, sync, and approval flows
+- **OpenClaw-native control plane** - named gateway profiles, external runtimes, reload modes, sync, and approval flows
 - **Agent builder + inspector** - personality/system tuning, skill management, and OpenClaw file editing
 - **Rich toolset** - shell, files, browser, git, sandbox execution, memory, MCP, and delegation
 - **Platform automation** - agents can manage tasks, schedules, chats, connectors, secrets, and more
@@ -289,6 +316,7 @@ Connector ingress now also supports optional pairing/allowlist policy:
 - `dmPolicy: allowlist` blocks unknown senders until approved
 - `/pair` flow lets approved admins generate and approve pairing codes
 - `/think` command can set connector thread thinking level (`low`, `medium`, `high`)
+- Session overrides also support per-thread `/reply`, `/scope`, `/thread`, `/provider`, `/model`, `/idle`, `/maxage`, and `/reset` controls
 
 ## Agent Tools
 
@@ -315,7 +343,7 @@ Agents can use the following tools when enabled:
 | Image Generation | Generate images from prompts (`generate_image`) via OpenAI, Stability, Replicate, fal.ai, Together, Fireworks, BFL, or custom endpoints; saved to uploads |
 | Email | Send outbound email via SMTP (`email`) with `send`/`status` actions |
 | Calendar | Manage Google/Outlook events (`calendar`) with list/create/update/delete/status actions |
-| Sandbox | Run JS/TS (Deno) or Python code in an isolated sandbox. Created files are returned as downloadable artifacts |
+| Sandbox | Run JS/TS in a Deno sandbox when custom code is necessary. If Deno is unavailable it fails closed with guidance; for simple API calls, prefer HTTP Request. |
 | MCP Servers | Connect to external Model Context Protocol servers. Tools from MCP servers are injected as first-class agent tools |
 
 ### Platform Tools
@@ -370,21 +398,6 @@ Daemon runtime also triggers memory consolidation (daily summary generation plus
 - **API:** `GET /api/daemon` (status), `POST /api/daemon` with `{"action": "start"}` or `{"action": "stop"}`
 - Auto-starts on first authenticated runtime traffic (`/api/auth` or `/api/daemon`) unless `SWARMCLAW_DAEMON_AUTOSTART=0`
 
-## Main Agent Loop
-
-For autonomous long-running missions, enable the **Main Loop** on an agent-thread or orchestrated chat. This lets an agent pursue a goal continuously with heartbeat-driven progress checks and automatic followups.
-
-- **Heartbeat prompts:** `SWARM_MAIN_MISSION_TICK` triggers on each heartbeat, giving the agent its goal, status, and pending events
-- **Auto-followup:** When an agent returns `[MAIN_LOOP_META] {"follow_up":true}`, the loop schedules another tick after `delay_sec`
-- **Mission state:** Tracks `goal`, `status` (idle/progress/blocked/ok), `summary`, `nextAction`, `autonomyMode` (assist/autonomous), and pending events
-- **Autonomy modes:**
-  - `autonomous`: Agent executes safe actions without confirmation, only asks when blocked by permissions/credentials
-  - `assist`: Agent asks before irreversible external actions (sending messages, purchases, account mutations)
-- **API:** `POST /api/chats/[id]/main-loop` with `{"tick":true}` to trigger a mission tick
-- **CLI:** `swarmclaw chats main-loop <id>` to inspect loop state, or `swarmclaw chats main-loop-action <id> --data '{"action":"nudge"}'` to control it
-
-Use this for background agents that should "keep working" on a goal until blocked or complete.
-
 ## Loop Modes
 
 Configure loop behavior in **Settings → Runtime & Loop Controls**:
@@ -657,7 +670,7 @@ npm run update:easy     # safe update helper for local installs
 SwarmClaw uses tag-based releases (`vX.Y.Z`) as the stable channel.
 
 ```bash
-# example patch release (v0.7.3 style)
+# example patch release (v0.7.4 style)
 npm version patch
 git push origin main --follow-tags
 ```
@@ -667,18 +680,15 @@ On `v*` tags, GitHub Actions will:
 2. Create a GitHub Release
 3. Build and publish Docker images to `ghcr.io/swarmclawai/swarmclaw` (`:vX.Y.Z`, `:latest`, `:sha-*`)
 
-#### v0.7.3 Release Readiness Notes
+#### v0.7.4 Release Readiness Notes
 
-Before shipping `v0.7.3`, confirm the following user-facing changes are reflected in docs:
+Before shipping `v0.7.4`, confirm the following user-facing changes are reflected in docs:
 
-1. New primitive plugins are documented in README and site docs: `mailbox`, `ask_human`, `document`, `extract`, `table`, and `crawl`.
-2. Browser persistence, higher-level browser actions, durable watch jobs, and delegation handles are covered in docs.
-3. Plugin docs mention canonical built-in IDs, source-backed installs/updates, hot reload, and encrypted `secret` settings.
-4. Plugin docs cover per-plugin workspaces and dependency installs for plugins that ship with a `package.json` manifest.
-5. Connector docs and CLI docs cover the connector doctor diagnostics endpoints/commands.
-6. The plugin tutorial reflects the current hook behavior, including `beforeToolExec` input rewriting and `settingsFields`.
-7. Site install/version strings are updated to `v0.7.3`, including the release notes index, install snippets, and sidebar footer.
-8. Provider docs mention that configured OpenAI models can populate the model dropdown while still allowing custom/manual entries.
+1. Sandbox docs are updated everywhere to reflect the current Deno-only `sandbox_exec` behavior and the guidance to prefer `http_request` for simple API calls.
+2. OpenClaw docs cover the current gateway/runtime behavior, including per-agent gateway routing, control-plane actions, and inspector-side advanced controls.
+3. Site and README install/version strings are updated to `v0.7.4`, including install snippets, release notes index text, and sidebar/footer labels.
+4. Release notes summarize the user-visible setup/auth/runtime changes from the current worktree, especially gateway/external-agent/setup flow improvements.
+5. CLI and tool docs do not reference removed or non-functional surfaces such as the old `openclaw_sandbox` bridge.
 
 ## CLI
 
@@ -713,9 +723,6 @@ swarmclaw agents list
 swarmclaw chats create --name "Main Ops" --agent-id <agentId>
 swarmclaw chats list
 
-# run a main loop action
-swarmclaw chats main-loop-action <chatId> --data '{"action":"nudge"}'
-
 # run setup diagnostics
 swarmclaw setup doctor
 ```

package/bin/package-manager.js

@@ -0,0 +1,157 @@
+'use strict'
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const LOCKFILE_NAMES = [
+  'package-lock.json',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+  'bun.lock',
+  'bun.lockb',
+]
+const INSTALL_METADATA_FILE = '.swarmclaw-install.json'
+
+function normalizePackageManager(raw) {
+  switch (String(raw || '').trim().toLowerCase()) {
+    case 'pnpm':
+    case 'yarn':
+    case 'bun':
+    case 'npm':
+      return String(raw).trim().toLowerCase()
+    default:
+      return null
+  }
+}
+
+function detectPackageManagerFromUserAgent(userAgent) {
+  const normalized = String(userAgent || '').toLowerCase()
+  if (normalized.startsWith('pnpm/')) return 'pnpm'
+  if (normalized.startsWith('yarn/')) return 'yarn'
+  if (normalized.startsWith('bun/')) return 'bun'
+  if (normalized.startsWith('npm/')) return 'npm'
+  return null
+}
+
+function readInstallMetadata(rootDir) {
+  const metadataPath = path.join(rootDir, INSTALL_METADATA_FILE)
+  if (!fs.existsSync(metadataPath)) return null
+  try {
+    const raw = JSON.parse(fs.readFileSync(metadataPath, 'utf8'))
+    return raw && typeof raw === 'object' ? raw : null
+  } catch {
+    return null
+  }
+}
+
+function detectPackageManager(rootDir, env = process.env) {
+  const envOverride = normalizePackageManager(env.SWARMCLAW_PACKAGE_MANAGER)
+  if (envOverride) return envOverride
+
+  const installMetadata = readInstallMetadata(rootDir)
+  const installManager = normalizePackageManager(installMetadata?.packageManager)
+  if (installManager) return installManager
+
+  if (fs.existsSync(path.join(rootDir, 'bun.lock')) || fs.existsSync(path.join(rootDir, 'bun.lockb'))) return 'bun'
+  if (fs.existsSync(path.join(rootDir, 'pnpm-lock.yaml'))) return 'pnpm'
+  if (fs.existsSync(path.join(rootDir, 'yarn.lock'))) return 'yarn'
+  if (fs.existsSync(path.join(rootDir, 'package-lock.json'))) return 'npm'
+
+  const userAgentManager = detectPackageManagerFromUserAgent(env.npm_config_user_agent)
+  if (userAgentManager) return userAgentManager
+  return 'npm'
+}
+
+function getInstallCommand(packageManager, omitDev = false) {
+  switch (packageManager) {
+    case 'pnpm':
+      return omitDev
+        ? { command: 'pnpm', args: ['install', '--prod'] }
+        : { command: 'pnpm', args: ['install'] }
+    case 'yarn':
+      return omitDev
+        ? { command: 'yarn', args: ['install', '--production=true'] }
+        : { command: 'yarn', args: ['install'] }
+    case 'bun':
+      return omitDev
+        ? { command: 'bun', args: ['install', '--production'] }
+        : { command: 'bun', args: ['install'] }
+    case 'npm':
+    default:
+      return omitDev
+        ? { command: 'npm', args: ['install', '--omit=dev'] }
+        : { command: 'npm', args: ['install'] }
+  }
+}
+
+function getGlobalUpdateCommand(packageManager, packageName) {
+  return getGlobalUpdateSpec(packageManager, packageName).display
+}
+
+function getGlobalUpdateSpec(packageManager, packageName) {
+  switch (packageManager) {
+    case 'pnpm':
+      return {
+        command: 'pnpm',
+        args: ['add', '-g', `${packageName}@latest`],
+        display: `pnpm add -g ${packageName}@latest`,
+      }
+    case 'yarn':
+      return {
+        command: 'yarn',
+        args: ['global', 'add', `${packageName}@latest`],
+        display: `yarn global add ${packageName}@latest`,
+      }
+    case 'bun':
+      return {
+        command: 'bun',
+        args: ['add', '-g', `${packageName}@latest`],
+        display: `bun add -g ${packageName}@latest`,
+      }
+    case 'npm':
+    default:
+      return {
+        command: 'npm',
+        args: ['update', '-g', packageName],
+        display: `npm update -g ${packageName}`,
+      }
+  }
+}
+
+function getRunScriptCommand(packageManager, scriptName) {
+  switch (packageManager) {
+    case 'pnpm':
+      return { command: 'pnpm', args: [scriptName] }
+    case 'yarn':
+      return { command: 'yarn', args: [scriptName] }
+    case 'bun':
+      return { command: 'bun', args: ['run', scriptName] }
+    case 'npm':
+    default:
+      return { command: 'npm', args: ['run', scriptName] }
+  }
+}
+
+function dependenciesChanged(diffText) {
+  if (!diffText) return false
+  return String(diffText)
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .some((file) => file === 'package.json' || LOCKFILE_NAMES.includes(file))
+}
+
+module.exports = {
+  dependenciesChanged,
+  detectPackageManager,
+  detectPackageManagerFromUserAgent,
+  getGlobalUpdateCommand,
+  getGlobalUpdateSpec,
+  getInstallCommand,
+  getRunScriptCommand,
+  INSTALL_METADATA_FILE,
+  LOCKFILE_NAMES,
+  normalizePackageManager,
+  readInstallMetadata,
+}

package/bin/package-manager.test.js

@@ -0,0 +1,90 @@
+'use strict'
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+const test = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const {
+  INSTALL_METADATA_FILE,
+  LOCKFILE_NAMES,
+  dependenciesChanged,
+  detectPackageManager,
+  detectPackageManagerFromUserAgent,
+  getGlobalUpdateSpec,
+  getInstallCommand,
+  getRunScriptCommand,
+} = require('./package-manager.js')
+
+test('detectPackageManagerFromUserAgent parses supported package managers', () => {
+  assert.equal(detectPackageManagerFromUserAgent('pnpm/10.6.1 npm/? node/v22.6.0 darwin arm64'), 'pnpm')
+  assert.equal(detectPackageManagerFromUserAgent('yarn/4.7.0 npm/? node/v22.6.0 darwin arm64'), 'yarn')
+  assert.equal(detectPackageManagerFromUserAgent('bun/1.2.10 npm/? node/v22.6.0 darwin arm64'), 'bun')
+  assert.equal(detectPackageManagerFromUserAgent('npm/10.9.2 node/v22.6.0 darwin arm64'), 'npm')
+})
+
+test('detectPackageManager prefers the lockfile present in the workspace', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-pm-'))
+
+  fs.writeFileSync(path.join(tmpDir, 'pnpm-lock.yaml'), 'lock', 'utf8')
+  assert.equal(detectPackageManager(tmpDir), 'pnpm')
+
+  fs.writeFileSync(path.join(tmpDir, 'bun.lockb'), 'lock', 'utf8')
+  assert.equal(detectPackageManager(tmpDir), 'bun')
+
+  fs.rmSync(tmpDir, { recursive: true, force: true })
+})
+
+test('detectPackageManager falls back to npm when no lockfile exists', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-pm-empty-'))
+  assert.equal(detectPackageManager(tmpDir), 'npm')
+  fs.rmSync(tmpDir, { recursive: true, force: true })
+})
+
+test('detectPackageManager uses install metadata when present', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-pm-meta-'))
+  fs.writeFileSync(
+    path.join(tmpDir, INSTALL_METADATA_FILE),
+    JSON.stringify({ packageManager: 'yarn' }),
+    'utf8',
+  )
+  assert.equal(detectPackageManager(tmpDir), 'yarn')
+  fs.rmSync(tmpDir, { recursive: true, force: true })
+})
+
+test('dependenciesChanged recognizes package.json and all supported lockfiles', () => {
+  assert.equal(dependenciesChanged('package.json\nsrc/app.ts'), true)
+  for (const lockfile of LOCKFILE_NAMES) {
+    assert.equal(dependenciesChanged(`${lockfile}\nREADME.md`), true)
+  }
+  assert.equal(dependenciesChanged('README.md\nsrc/index.ts'), false)
+})
+
+test('getInstallCommand returns manager-specific install arguments', () => {
+  assert.deepEqual(getInstallCommand('npm', true), { command: 'npm', args: ['install', '--omit=dev'] })
+  assert.deepEqual(getInstallCommand('pnpm', false), { command: 'pnpm', args: ['install'] })
+  assert.deepEqual(getInstallCommand('yarn', true), { command: 'yarn', args: ['install', '--production=true'] })
+  assert.deepEqual(getInstallCommand('bun', true), { command: 'bun', args: ['install', '--production'] })
+})
+
+test('getRunScriptCommand returns manager-specific script launchers', () => {
+  assert.deepEqual(getRunScriptCommand('npm', 'build'), { command: 'npm', args: ['run', 'build'] })
+  assert.deepEqual(getRunScriptCommand('pnpm', 'start'), { command: 'pnpm', args: ['start'] })
+  assert.deepEqual(getRunScriptCommand('yarn', 'dev'), { command: 'yarn', args: ['dev'] })
+  assert.deepEqual(getRunScriptCommand('bun', 'start'), { command: 'bun', args: ['run', 'start'] })
+})
+
+test('getGlobalUpdateSpec returns manager-specific update commands', () => {
+  assert.deepEqual(getGlobalUpdateSpec('npm', '@swarmclawai/swarmclaw'), {
+    command: 'npm',
+    args: ['update', '-g', '@swarmclawai/swarmclaw'],
+    display: 'npm update -g @swarmclawai/swarmclaw',
+  })
+  assert.deepEqual(getGlobalUpdateSpec('pnpm', '@swarmclawai/swarmclaw'), {
+    command: 'pnpm',
+    args: ['add', '-g', '@swarmclawai/swarmclaw@latest'],
+    display: 'pnpm add -g @swarmclawai/swarmclaw@latest',
+  })
+})

package/bin/server-cmd.js

@@ -1,10 +1,16 @@
 #!/usr/bin/env node
 'use strict'
+/* eslint-disable @typescript-eslint/no-require-imports */
 
 const fs = require('node:fs')
 const path = require('node:path')
-const { spawn, execSync } = require('node:child_process')
+const { spawn, execFileSync } = require('node:child_process')
 const os = require('node:os')
+const {
+  LOCKFILE_NAMES,
+  detectPackageManager,
+  getInstallCommand,
+} = require('./package-manager.js')
 
 // ---------------------------------------------------------------------------
 // Paths
@@ -26,7 +32,7 @@ const BUILD_COPY_ENTRIES = [
   'tsconfig.json',
   'postcss.config.mjs',
   'package.json',
-  'package-lock.json',
+  ...LOCKFILE_NAMES,
 ]
 
 // ---------------------------------------------------------------------------
@@ -73,13 +79,26 @@ function symlinkPath(src, dest) {
   fs.symlinkSync(src, dest)
 }
 
+function readBuiltInfo() {
+  if (!fs.existsSync(BUILT_MARKER)) return null
+  try {
+    const raw = JSON.parse(fs.readFileSync(BUILT_MARKER, 'utf8'))
+    return raw && typeof raw === 'object' ? raw : null
+  } catch {
+    return null
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Build
 // ---------------------------------------------------------------------------
 
 function needsBuild(forceBuild) {
   if (forceBuild) return true
-  if (!fs.existsSync(BUILT_MARKER)) return true
+  const info = readBuiltInfo()
+  if (!info) return true
+  if (info.version !== getVersion()) return true
+  if (!findStandaloneServer()) return true
   return false
 }
 
@@ -110,15 +129,18 @@ function runBuild() {
     symlinkPath(nmSrc, nmDest)
   } else {
     // If node_modules doesn't exist at PKG_ROOT, install
-    log('Installing dependencies...')
-    execSync('npm install', { cwd: SWARMCLAW_HOME, stdio: 'inherit' })
+    const packageManager = detectPackageManager(SWARMCLAW_HOME, process.env)
+    const install = getInstallCommand(packageManager)
+    log(`Installing dependencies with ${packageManager}...`)
+    execFileSync(install.command, install.args, { cwd: SWARMCLAW_HOME, stdio: 'inherit' })
   }
 
   // Run Next.js build
   log('Building Next.js application (this may take a minute)...')
   // Use webpack for production build reliability in packaged/fresh-install
   // environments (Turbopack has intermittently failed during prerender).
-  execSync('npx next build --webpack', {
+  const nextCli = path.join(SWARMCLAW_HOME, 'node_modules', 'next', 'dist', 'bin', 'next')
+  execFileSync(process.execPath, [nextCli, 'build', '--webpack'], {
     cwd: SWARMCLAW_HOME,
     stdio: 'inherit',
     env: {
@@ -373,4 +395,13 @@ function main() {
   startServer({ port, wsPort, host, detach })
 }
 
-main()
+if (require.main === module) {
+  main()
+}
+
+module.exports = {
+  getVersion,
+  main,
+  needsBuild,
+  readBuiltInfo,
+}

package/bin/swarmclaw.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 'use strict'
+/* eslint-disable @typescript-eslint/no-require-imports */
 
 const path = require('node:path')
 const { spawnSync } = require('node:child_process')
@@ -34,12 +35,45 @@ function shouldUseLegacyTsCli(argv) {
   return actions.has(action)
 }
 
+function supportsStripTypes() {
+  return process.allowedNodeEnvironmentFlags.has('--experimental-strip-types')
+}
+
+function hasTsxRuntime() {
+  try {
+    require.resolve('tsx/package.json')
+    return true
+  } catch {
+    return false
+  }
+}
+
+function buildLegacyTsCliArgs(cliPath, argv, options = {}) {
+  const stripTypesSupported = options.supportsStripTypes ?? supportsStripTypes()
+  if (stripTypesSupported) {
+    return ['--no-warnings', '--experimental-strip-types', cliPath, ...argv]
+  }
+
+  const tsxAvailable = options.hasTsxRuntime ?? hasTsxRuntime()
+  if (tsxAvailable) {
+    return ['--no-warnings', '--import', 'tsx', cliPath, ...argv]
+  }
+
+  return null
+}
+
 function runLegacyTsCli(argv) {
   const cliPath = path.join(__dirname, '..', 'src', 'cli', 'index.ts')
+  const args = buildLegacyTsCliArgs(cliPath, argv)
+  const env = normalizeLegacyCliEnv(process.env)
+  if (!args) {
+    process.stderr.write('Legacy CLI commands require Node 22.6+ or an available local tsx runtime.\n')
+    return 1
+  }
   const child = spawnSync(
     process.execPath,
-    ['--no-warnings', '--experimental-strip-types', cliPath, ...argv],
-    { stdio: 'inherit' },
+    args,
+    { stdio: 'inherit', env },
   )
 
   if (child.error) {
@@ -50,6 +84,18 @@ function runLegacyTsCli(argv) {
   return 1
 }
 
+function normalizeLegacyCliEnv(env) {
+  const nextEnv = { ...env }
+  if (!nextEnv.SWARMCLAW_URL && nextEnv.SWARMCLAW_BASE_URL) {
+    nextEnv.SWARMCLAW_URL = nextEnv.SWARMCLAW_BASE_URL
+  }
+  if (!nextEnv.SWARMCLAW_ACCESS_KEY) {
+    const key = nextEnv.SWARMCLAW_API_KEY || nextEnv.SC_ACCESS_KEY || ''
+    if (key) nextEnv.SWARMCLAW_ACCESS_KEY = key
+  }
+  return nextEnv
+}
+
 async function runMappedCli(argv) {
   const cliPath = path.join(__dirname, '..', 'src', 'cli', 'index.js')
   const cliModule = await import(cliPath)
@@ -66,11 +112,11 @@ async function main() {
 
   // Route 'server' and 'update' subcommands to CJS scripts (no TS dependency).
   if (top === 'server') {
-    require('./server-cmd.js')
+    require('./server-cmd.js').main()
     return
   }
   if (top === 'update') {
-    require('./update-cmd.js')
+    require('./update-cmd.js').main()
     return
   }
 
@@ -86,6 +132,10 @@ if (require.main === module) {
 }
 
 module.exports = {
+  buildLegacyTsCliArgs,
+  hasTsxRuntime,
   TS_CLI_ACTIONS,
+  normalizeLegacyCliEnv,
+  supportsStripTypes,
   shouldUseLegacyTsCli,
 }