@swarmclawai/swarmclaw 0.7.2 → 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.2 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
@@ -249,6 +276,8 @@ src/
 | xAI (Grok) | api.x.ai | Grok 3, Grok 3 Fast, Grok 3 Mini |
 | Fireworks AI | api.fireworks.ai | DeepSeek R1, Llama 3.3 70B, Qwen 3 |
 
+If a provider is configured, SwarmClaw can populate the model dropdown from that provider’s advertised model list. For OpenAI this means the selector can auto-fill current OpenAI models, while still allowing users to type a newer or custom model manually if it is not in the fetched list yet.
+
 ### Local & Remote
 
 | Provider | Type | Notes |
@@ -287,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
 
@@ -301,18 +331,19 @@ Agents can use the following tools when enabled:
 | Edit File | Search-and-replace editing (exact match required) |
 | Web Search | Search the web via DuckDuckGo HTML scraping |
 | Web Fetch | Fetch and extract text content from URLs (uses cheerio) |
-| CLI Delegation | Delegate complex tasks to Claude Code, Codex CLI, OpenCode CLI, or Gemini CLI |
-| Spawn Subagent | Delegate a sub-task to another agent and capture its response in the current run |
-| Browser | Playwright-powered web browsing via MCP (navigate, click, type, screenshot, PDF) |
+| CLI Delegation | Delegate complex tasks to Claude Code, Codex CLI, OpenCode CLI, or Gemini CLI, either inline or as a background job handle |
+| Spawn Subagent | Delegate a sub-task to another agent with `status` / `list` / `wait` / `cancel` handles and inherited browser state when needed |
+| Browser | Playwright-powered web browsing via MCP with persistent profiles, structured page reads, form helpers, verification actions, and resumable state |
 | Canvas | Present/hide/snapshot live HTML content in a chat canvas panel |
 | HTTP Request | Make direct API calls with method, headers, body, redirect control, and timeout |
 | Git | Run structured git subcommands (`status`, `diff`, `log`, `add`, `commit`, `push`, etc.) with repo safety checks |
 | Memory | Store and retrieve long-term memories with FTS5 + vector search, file references, image attachments, and linked memory graph traversal |
+| Monitor | Inspect system state and create durable watches over files, endpoints, tasks, webhooks, and page/content changes (`monitor_tool`) |
 | Wallet | Manage an agent-linked Solana wallet (`wallet_tool`) to check balance/address, send SOL (limits + approval), and review transaction history |
 | 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
@@ -324,7 +355,7 @@ Agents with platform tools enabled can manage the SwarmClaw instance:
 | Manage Agents | List, create, update, delete agents |
 | Manage Tasks | Create and manage task board items with agent assignment |
 | Manage Schedules | Create cron, interval, or one-time scheduled jobs |
-| Reminders | Schedule a conversational wake event in the current chat (`schedule_wake`) |
+| Reminders | Schedule a durable conversational wake event in the current chat (`schedule_wake`) |
 | Manage Skills | List, create, update reusable skill definitions |
 | Manage Documents | Upload/search/get/delete indexed docs for lightweight RAG workflows |
 | Manage Webhooks | Register external webhook endpoints that trigger agent chats |
@@ -367,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**:
@@ -440,9 +456,9 @@ Agents and chats can have **fallback credentials**. If the primary API key gets
 
 ## Plugin System
 
-SwarmClaw features a powerful, modular plugin system designed for both agent enhancement and application extensibility. It is fully compatible with the **OpenClaw** plugin format.
+SwarmClaw features a modular plugin system for agent capabilities, UI extensions, provider/connectors, and post-turn automation. It supports the native SwarmClaw hook/tool format and the **OpenClaw** register/activate formats.
 
-Plugins can be managed in **Settings → Plugins** and installed via the Marketplace, URL, or by dropping `.js` files into `data/plugins/`.
+Plugins can be managed in **Settings → Plugins** and installed via the Marketplace, HTTPS URL, or by dropping `.js` / `.mjs` files into `data/plugins/`.
 
 Docs:
 - Full docs: https://swarmclaw.ai/docs
@@ -453,17 +469,30 @@ Docs:
 Unlike standard tool systems, SwarmClaw plugins can modify the application itself:
 
 - **Agent Tools**: Define custom tools that agents can autonomously discover and use.
-- **Lifecycle Hooks**: Intercept events like `beforeAgentStart`, `afterToolExec`, and `onMessage`.
+- **Lifecycle Hooks**: Intercept events like `beforeAgentStart`, `beforeToolExec`, `afterToolExec`, `afterChatTurn`, and `onMessage`.
 - **UI Extensions**:
   - `sidebarItems`: Inject new navigation links into the main sidebar.
   - `headerWidgets`: Add status badges or indicators to the chat header (e.g., Wallet Balance).
   - `chatInputActions`: Add custom action buttons next to the chat input (e.g., "Quick Scan").
   - `plugin-ui` Messages: Render rich, interactive React cards in the chat stream.
 - **Deep Chat Hooks**:
-  - `transformInboundMessage`: Modify user messages before they reach the agent.
-  - `transformOutboundMessage`: Modify agent responses before they are saved or displayed.
+  - `transformInboundMessage`: Modify user messages before they reach the agent runtime.
+  - `transformOutboundMessage`: Modify agent responses before they are persisted or displayed.
+  - `beforeToolExec`: Can rewrite tool input before the selected tool executes.
 - **Custom Providers**: Add new LLM backends (e.g., a specialized local model or a new API).
 - **Custom Connectors**: Build new chat platform bridges (e.g., a proprietary internal messenger).
+- **Per-plugin Settings**: Declare `ui.settingsFields` and read/write them via `/api/plugins/settings`. Fields marked `type: 'secret'` are encrypted at rest.
+
+### Canonical Plugin IDs
+
+Built-in capabilities now resolve to a single canonical plugin family ID across agent configs, policy rules, approvals, and the Plugins UI. Legacy aliases still work, but the canonical IDs are what you should document and store going forward.
+
+- `manage_sessions` instead of `session_info`
+- `manage_connectors` instead of `connectors`
+- `http_request` instead of `http`
+- `spawn_subagent` instead of `subagent`
+- `manage_chatrooms` instead of `chatroom`
+- `schedule_wake` instead of `schedule`
 
 ### Autonomous Capability Discovery
 
@@ -494,12 +523,53 @@ module.exports = {
 };
 ```
 
+Hook signatures of note:
+
+- `beforeToolExec({ toolName, input })` may return a replacement input object.
+- `afterToolExec({ session, toolName, input, output })` observes completed tool executions.
+- `transformInboundMessage({ session, text })` and `transformOutboundMessage({ session, text })` run sequentially across enabled plugins.
+
+### Building Plugins
+
+The shortest reliable workflow for a new plugin:
+
+1. Create a focused `.js` or `.mjs` file under `data/plugins/`.
+2. Export `name`, `description`, any `hooks`, and optional `tools` / `ui.settingsFields`.
+3. Keep tool outputs structured when the agent needs to chain them into later steps.
+4. Use `settingsFields` for secrets or environment-specific values instead of hardcoding them.
+5. If the plugin needs third-party npm packages, attach a `package.json` manifest so SwarmClaw can manage it in a per-plugin workspace.
+6. Enable the plugin in **Settings → Plugins** and test both the tool path and any hook behavior.
+7. If you host it remotely, install from a stable HTTPS URL so SwarmClaw can record source metadata and update it later.
+
+A fuller step-by-step walkthrough lives at https://swarmclaw.ai/docs/plugin-tutorial.
+
 ### Lifecycle Management
 
 - **Versioning**: All plugins support semantic versioning (e.g., `v1.2.3`).
-- **Updates**: Plugins can be updated individually or in bulk via the Plugins manager.
-- **Hot-Reload**: The system automatically reloads plugin logic when a file is updated or a new plugin is installed.
-- **Stability Guardrails**: Consecutive plugin failures are tracked in `data/plugin-failures.json`; failing plugins are auto-disabled, a warning notification is emitted in-app, and users can re-enable manually from the Plugins manager.
+- **Updates**: External plugins installed from a recorded source URL can be updated individually or in bulk via the Plugins manager. Built-ins update with the app release.
+- **Hot Reload**: Changes inside `data/plugins/` invalidate the plugin registry automatically, and installs/updates trigger an immediate reload.
+- **Plugin Workspaces**: Plugins with a manifest are managed under `data/plugins/.workspaces/<plugin>/`, and dependency installs can be triggered from the plugin detail sheet or `POST /api/plugins/dependencies`.
+- **Stability Guardrails**: Consecutive plugin failures are tracked in `data/plugin-failures.json`; failing external plugins are auto-disabled, a warning notification is emitted in-app, and users can re-enable manually from the Plugins manager.
+- **Source Metadata**: Marketplace/URL installs record the normalized source URL and source hash in `data/plugins.json`.
+- **Settings Safety**: Plugin settings are validated against declared `settingsFields`; unknown keys are ignored and `secret` values are stored encrypted.
+
+### Browser, Watch, and Delegation Upgrades
+
+- **Persistent Browser Profiles**: The built-in `browser` plugin now keeps a reusable profile per chat/session, and subagents inherit the parent profile by default. Profiles live under `~/.swarmclaw/browser-profiles` unless you override `BROWSER_PROFILES_DIR`, so cookies, storage, and authenticated state survive longer-running work without polluting the project tree. Browser state is exposed at `GET /api/chats/[id]/browser`.
+- **Higher-Level Browser Actions**: In addition to raw Playwright-style actions, `browser` supports workflow-oriented actions such as `read_page`, `extract_links`, `extract_form_fields`, `extract_table`, `fill_form`, `submit_form`, `scroll_until`, `download_file`, `complete_web_task`, `verify_text`, `verify_element`, `verify_list`, `verify_value`, `profile`, and `reset_profile`.
+- **Structured Browser State**: Browser sessions persist recent observations, tabs, artifacts (screenshots / PDFs / downloads), current URL, and last errors in `browser_sessions`, which makes autonomous browser tasks easier to resume, inspect, and hand off across turns.
+- **Durable Watches**: `schedule_wake` now uses persisted watch jobs instead of an in-memory timer, and `monitor_tool` supports `create_watch`, `list_watches`, `get_watch`, and `cancel_watch` across `time`, `http`, `file`, `task`, `webhook`, and `page` conditions. The same watch system also powers the new `mailbox`, session-mailbox, and approval waits used by human-loop flows. Watches support common checks like status/status sets, regex or text matches, content changes, existence checks, inbound mailbox correlation IDs, and webhook event filters.
+- **Long-Running Delegation Handles**: `delegate` and `spawn_subagent` support handle-based flows instead of only synchronous final text. Use `background=true` or `waitForCompletion=false` to launch long-running work, then inspect or stop it with `action=status|list|wait|cancel`.
+- **Delegation Job Persistence**: Delegate and subagent runs are recorded in `delegation_jobs` with checkpoints, backend/session metadata, resume IDs, child session IDs, and terminal-status recovery after daemon restarts. Late completions no longer overwrite cancelled jobs.
+
+### New Primitive Plugins
+
+- **Mailbox / Inbox Automation**: The built-in `mailbox` plugin adds IMAP/SMTP inbox access with `status`, `list_messages`, `list_threads`, `search_messages`, `read_message`, `download_attachment`, `reply`, and `wait_for_email`. It supports durable inbound-email waits and reuses plugin settings / connector config where possible. Configure it in **Settings → Plugins** with `imapHost`, `smtpHost`, `user`, `password`, and optional reply defaults.
+- **Human-in-the-Loop Requests**: The built-in `ask_human` plugin provides `request_input`, `request_approval`, `wait_for_reply`, `wait_for_approval`, `list_mailbox`, `ack_mailbox`, and `status`. It is backed by session mailbox envelopes plus approval records so agents can pause and resume on real human responses instead of polling ad hoc state.
+- **Document Parsing / OCR**: The built-in `document` plugin adds `read`, `metadata`, `ocr`, `extract_tables`, `store`, `list`, `search`, `get`, and `delete`. It uses the shared document extraction helpers for PDFs, Office docs, OCR-able images, HTML, CSV/TSV/XLSX, ZIP inspection, and plain text files.
+- **Schema-Driven Extraction**: The built-in `extract` plugin adds `extract_structured` and `summarize`, using the current session model/provider to turn raw text or local files into validated JSON objects. This is the primitive to combine with browser / document / crawl output when an agent needs structured records instead of prose.
+- **Tabular Data Operations**: The built-in `table` plugin adds `read`, `load_csv`, `load_xlsx`, `summarize`, `filter`, `sort`, `group`, `pivot`, `dedupe`, `join`, and `write`. It operates on CSV, TSV, JSON array-of-objects, or XLSX inputs without forcing agents to drop into shell or Python for basic spreadsheet work, and transformed tables can be persisted with `outputPath` / `saveTo`.
+- **Multi-Page Crawling**: The built-in `crawl` plugin adds `crawl_site`, `follow_pagination`, `extract_sitemap`, `dedupe_pages`, and `batch_extract`. It handles BFS-style same-origin site traversal, accepts either a fresh start URL or an explicit page list, and can hand the aggregate page set directly into structured extraction for research-heavy autonomous tasks.
 
 ## Deploy to a VPS
 
@@ -600,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.2 style)
+# example patch release (v0.7.4 style)
 npm version patch
 git push origin main --follow-tags
 ```
@@ -610,16 +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.2 Release Readiness Notes
+#### v0.7.4 Release Readiness Notes
 
-Before shipping `v0.7.2`, 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. `sessions` → `chats` naming is consistent in README, site docs, and CLI/API examples.
-2. New built-in plugins/tools are documented (`image_gen`, `email`, `calendar`) including settings expectations.
-3. Plugin settings support is documented (`settingsFields`, `/api/plugins/settings` read/write endpoints).
-4. Usage telemetry docs include plugin rollups (`byPlugin`) and plugin token usage dashboard context.
-5. Gemini CLI delegation support and `geminiResumeId` task metadata are documented where CLI sessions are described.
-6. Site release notes include a `v0.7.2` section and docs index points to the current release notes version.
+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
 
@@ -654,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',
+  })
+})