@swarmclawai/swarmclaw 1.0.0 → 1.0.3

package/README.md

@@ -136,6 +136,17 @@ Running `swarmclaw` with no arguments starts the server on `http://localhost:345
 Global install runs `postinstall`, which rebuilds `better-sqlite3` and prepares the sandbox browser image when Docker is available.
 If Docker is not installed yet, SwarmClaw keeps running and falls back to host execution for shell, browser, and `sandbox_exec`.
 No Deno install is required for the local `sandbox_exec` path.
+Runtime state defaults to `~/.swarmclaw` unless you set `SWARMCLAW_HOME`.
+If the standalone server bundle is missing, the first launch builds it under `<swarmclaw-home>/builds/package-<version>` before starting.
+
+### Local project install
+
+```bash
+npm i @swarmclawai/swarmclaw
+npx swarmclaw
+```
+
+Local installs keep runtime state in `<project>/.swarmclaw` by default. The same project-local install works with `pnpm`, `yarn`, or `bun`; use that package manager's exec command to launch the local binary, or run `./node_modules/.bin/swarmclaw` directly.
 
 ### One-off run
 
@@ -146,6 +157,8 @@ yarn dlx @swarmclawai/swarmclaw
 bunx @swarmclawai/swarmclaw
 ```
 
+One-off runs use the published package without keeping a project-local install. Runtime state defaults to `~/.swarmclaw` unless you set `SWARMCLAW_HOME`.
+
 ### Install script
 
 ```bash
@@ -155,7 +168,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.
 It also builds the production bundle so `npm run start` is ready immediately after install.
 No Deno install is required; local sandbox execution is Docker-first with automatic host Node fallback.
-To pin a version: `SWARMCLAW_VERSION=v0.9.6 curl ... | bash`
+To pin a version: `SWARMCLAW_VERSION=v1.0.3 curl ... | bash`
 
 Or run locally from the repo (friendly for non-technical users):
 
@@ -603,7 +616,7 @@ A fuller step-by-step walkthrough lives at https://swarmclaw.ai/docs/plugin-tuto
 
 ### 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`.
+- **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-home>/browser-profiles` by default (`~/.swarmclaw/browser-profiles` for global installs, `<project>/.swarmclaw/browser-profiles` for local installs) 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.

package/bin/doctor-cmd.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+'use strict'
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { readPackageVersion } = require('./install-root.js')
+const {
+  PKG_ROOT,
+  SWARMCLAW_HOME,
+  findStandaloneServer,
+  isGitCheckout,
+  resolvePackageBuildRoot,
+  resolveInstalledNext,
+} = require('./server-cmd.js')
+
+function readPid(pidFile) {
+  try {
+    const pid = Number.parseInt(fs.readFileSync(pidFile, 'utf8').trim(), 10)
+    return Number.isFinite(pid) ? pid : null
+  } catch {
+    return null
+  }
+}
+
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function buildDoctorReport(opts = {}) {
+  const pkgRoot = opts.pkgRoot || PKG_ROOT
+  const homeDir = opts.homeDir || SWARMCLAW_HOME
+  const pidFile = path.join(homeDir, 'server.pid')
+  const dataDir = path.join(homeDir, 'data')
+  const workspaceDir = path.join(homeDir, 'workspace')
+  const browserProfilesDir = path.join(homeDir, 'browser-profiles')
+  const nextInstall = resolveInstalledNext(pkgRoot)
+  const nextCliPath = nextInstall?.nextCli || path.join(pkgRoot, 'node_modules', 'next', 'dist', 'bin', 'next')
+  const standaloneServer = findStandaloneServer({ pkgRoot })
+  const buildRoot = resolvePackageBuildRoot(pkgRoot)
+  const pid = readPid(pidFile)
+  const running = pid ? isProcessRunning(pid) : false
+
+  const serverState = !pid
+    ? 'not-running'
+    : running
+      ? 'running'
+      : 'stale-pid'
+
+  const recommendations = []
+  if (!standaloneServer) {
+    if (fs.existsSync(nextCliPath)) {
+      recommendations.push('Standalone bundle is missing. Run `swarmclaw run` to build it automatically or `swarmclaw server --build` to prebuild it now.')
+    } else {
+      recommendations.push('Next.js build dependencies are missing from this install. Reinstall the package before starting SwarmClaw.')
+    }
+  }
+  if (serverState === 'stale-pid') {
+    recommendations.push('A stale PID file was found. Run `swarmclaw stop` to clean it up.')
+  }
+
+  return {
+    packageVersion: readPackageVersion(pkgRoot) || 'unknown',
+    packageRoot: pkgRoot,
+    buildRoot,
+    installKind: isGitCheckout(pkgRoot) ? 'git' : 'package',
+    homeDir,
+    dataDir,
+    workspaceDir,
+    browserProfilesDir,
+    server: {
+      state: serverState,
+      pid,
+      pidFile,
+    },
+    build: {
+      standaloneServer,
+      nextCliPresent: fs.existsSync(nextCliPath),
+      nextCliPath,
+    },
+    recommendations,
+  }
+}
+
+function printHelp() {
+  process.stdout.write(`
+Usage: swarmclaw doctor [--json]
+
+Show local installation and build diagnostics for SwarmClaw.
+`.trim() + '\n')
+}
+
+function printHumanReport(report) {
+  const lines = [
+    `Package version: ${report.packageVersion}`,
+    `Install kind: ${report.installKind}`,
+    `Package root: ${report.packageRoot}`,
+    `Build root: ${report.buildRoot}`,
+    `Home: ${report.homeDir}`,
+    `Data: ${report.dataDir}`,
+    `Workspace: ${report.workspaceDir}`,
+    `Browser profiles: ${report.browserProfilesDir}`,
+    `Server: ${report.server.state}${report.server.pid ? ` (PID: ${report.server.pid})` : ''}`,
+    `Standalone bundle: ${report.build.standaloneServer ? `yes (${report.build.standaloneServer})` : 'no'}`,
+    `Next CLI available: ${report.build.nextCliPresent ? 'yes' : 'no'}`,
+  ]
+
+  if (report.recommendations.length > 0) {
+    lines.push('', 'Recommendations:')
+    for (const recommendation of report.recommendations) {
+      lines.push(`- ${recommendation}`)
+    }
+  }
+
+  process.stdout.write(`${lines.join('\n')}\n`)
+}
+
+function main(args = process.argv.slice(3)) {
+  const json = args.includes('--json')
+  if (args.includes('-h') || args.includes('--help')) {
+    printHelp()
+    process.exit(0)
+  }
+
+  const unknown = args.filter((arg) => arg !== '--json')
+  if (unknown.length > 0) {
+    process.stderr.write(`[swarmclaw] Unknown argument: ${unknown[0]}\n`)
+    printHelp()
+    process.exit(1)
+  }
+
+  const report = buildDoctorReport()
+  if (json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+    return
+  }
+  printHumanReport(report)
+}
+
+if (require.main === module) {
+  main()
+}
+
+module.exports = {
+  buildDoctorReport,
+  isProcessRunning,
+  main,
+  readPid,
+}

package/bin/doctor-cmd.test.js

@@ -0,0 +1,50 @@
+'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 { buildDoctorReport } = require('./doctor-cmd.js')
+
+test('buildDoctorReport recommends a local build when standalone output is missing', () => {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-doctor-'))
+  const pkgRoot = path.join(tempDir, 'pkg')
+  const homeDir = path.join(tempDir, '.swarmclaw')
+  const nextCli = path.join(pkgRoot, 'node_modules', 'next', 'dist', 'bin', 'next')
+
+  fs.mkdirSync(path.dirname(nextCli), { recursive: true })
+  fs.mkdirSync(homeDir, { recursive: true })
+  fs.writeFileSync(path.join(pkgRoot, 'package.json'), JSON.stringify({ name: '@swarmclawai/swarmclaw', version: '1.0.1' }), 'utf8')
+  fs.writeFileSync(nextCli, '#!/usr/bin/env node\n', 'utf8')
+
+  const report = buildDoctorReport({ pkgRoot, homeDir })
+
+  assert.equal(report.installKind, 'package')
+  assert.equal(report.build.nextCliPresent, true)
+  assert.equal(report.build.standaloneServer, null)
+  assert.match(report.recommendations.join('\n'), /swarmclaw run/)
+
+  fs.rmSync(tempDir, { recursive: true, force: true })
+})
+
+test('buildDoctorReport flags stale PID files', () => {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-doctor-stale-'))
+  const pkgRoot = path.join(tempDir, 'pkg')
+  const homeDir = path.join(tempDir, '.swarmclaw')
+  const pidFile = path.join(homeDir, 'server.pid')
+
+  fs.mkdirSync(homeDir, { recursive: true })
+  fs.mkdirSync(pkgRoot, { recursive: true })
+  fs.writeFileSync(path.join(pkgRoot, 'package.json'), JSON.stringify({ name: '@swarmclawai/swarmclaw', version: '1.0.1' }), 'utf8')
+  fs.writeFileSync(pidFile, '999999\n', 'utf8')
+
+  const report = buildDoctorReport({ pkgRoot, homeDir })
+
+  assert.equal(report.server.state, 'stale-pid')
+  assert.match(report.recommendations.join('\n'), /swarmclaw stop/)
+
+  fs.rmSync(tempDir, { recursive: true, force: true })
+})

package/bin/install-root.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 'use strict'
 
+/* eslint-disable @typescript-eslint/no-require-imports */
 const fs = require('node:fs')
 const os = require('node:os')
 const path = require('node:path')
@@ -143,13 +144,51 @@ function detectGlobalInstallManagerForRoot(pkgRoot, execImpl = execFileSync, env
   return null
 }
 
+function findLocalInstallProjectRoot(pkgRoot) {
+  const normalized = normalizeDir(pkgRoot)
+  if (!normalized) return null
+
+  const marker = `${path.sep}node_modules${path.sep}`
+  const idx = normalized.indexOf(marker)
+  if (idx === -1) return null
+
+  const projectRoot = normalized.slice(0, idx)
+  return projectRoot ? path.resolve(projectRoot) : path.parse(normalized).root
+}
+
+function resolveStateHome(opts = {}) {
+  const env = opts.env || process.env
+  const explicitHome = normalizeDir(env.SWARMCLAW_HOME)
+  if (explicitHome) return explicitHome
+
+  const pkgRoot = normalizeDir(opts.pkgRoot)
+    || resolvePackageRoot({
+      moduleDir: opts.moduleDir,
+      argv1: opts.argv1,
+      cwd: opts.cwd,
+    })
+  if (!pkgRoot) return path.join(os.homedir(), '.swarmclaw')
+
+  const execImpl = opts.execImpl || execFileSync
+  if (detectGlobalInstallManagerForRoot(pkgRoot, execImpl, env)) {
+    return path.join(os.homedir(), '.swarmclaw')
+  }
+
+  const projectRoot = findLocalInstallProjectRoot(pkgRoot)
+  if (projectRoot) return path.join(projectRoot, '.swarmclaw')
+
+  return path.join(os.homedir(), '.swarmclaw')
+}
+
 module.exports = {
   PACKAGE_NAME,
   candidateDirsFromArgv1,
   detectGlobalInstallManagerForRoot,
   findPackageRoot,
+  findLocalInstallProjectRoot,
   readPackageName,
   readPackageVersion,
   resolveGlobalRoot,
   resolvePackageRoot,
+  resolveStateHome,
 }

package/bin/install-root.test.js

@@ -10,7 +10,9 @@ const path = require('node:path')
 const {
   candidateDirsFromArgv1,
   detectGlobalInstallManagerForRoot,
+  findLocalInstallProjectRoot,
   resolvePackageRoot,
+  resolveStateHome,
 } = require('./install-root.js')
 
 test('candidateDirsFromArgv1 includes the package directory for node_modules/.bin launchers', () => {
@@ -59,3 +61,61 @@ test('detectGlobalInstallManagerForRoot matches the owning global root by realpa
 
   fs.rmSync(rootDir, { recursive: true, force: true })
 })
+
+test('findLocalInstallProjectRoot returns the project root for nested pnpm installs', () => {
+  const pkgRoot = path.join(
+    '/tmp',
+    'example',
+    'node_modules',
+    '.pnpm',
+    '@swarmclawai+swarmclaw@1.0.1',
+    'node_modules',
+    '@swarmclawai',
+    'swarmclaw',
+  )
+
+  assert.equal(findLocalInstallProjectRoot(pkgRoot), path.join('/tmp', 'example'))
+})
+
+test('resolveStateHome prefers the local project .swarmclaw directory for local installs', () => {
+  const projectRoot = path.join('/tmp', 'example')
+  const pkgRoot = path.join(projectRoot, 'node_modules', '@swarmclawai', 'swarmclaw')
+  const execImpl = () => {
+    throw new Error('unexpected global root lookup')
+  }
+
+  assert.equal(
+    resolveStateHome({
+      pkgRoot,
+      env: {},
+      execImpl,
+    }),
+    path.join(projectRoot, '.swarmclaw'),
+  )
+})
+
+test('resolveStateHome keeps global installs under the user home directory', () => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-state-home-'))
+  const npmGlobalRoot = path.join(rootDir, 'npm-global')
+  const pkgRoot = path.join(npmGlobalRoot, '@swarmclawai', 'swarmclaw')
+
+  fs.mkdirSync(path.join(npmGlobalRoot, '@swarmclawai'), { recursive: true })
+  fs.mkdirSync(pkgRoot, { recursive: true })
+
+  const execImpl = (command, args) => {
+    if (command === 'npm' && args.join(' ') === 'root -g') return npmGlobalRoot
+    if (command === 'pnpm' && args.join(' ') === 'root -g') return path.join(rootDir, 'pnpm-global')
+    throw new Error(`unexpected command: ${command} ${args.join(' ')}`)
+  }
+
+  assert.equal(
+    resolveStateHome({
+      pkgRoot,
+      env: {},
+      execImpl,
+    }),
+    path.join(os.homedir(), '.swarmclaw'),
+  )
+
+  fs.rmSync(rootDir, { recursive: true, force: true })
+})