@agentsdock/server 1.0.7-beta.5

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,19 @@
+AgentsDock
+Copyright 2026 Zhengyi Luo and contributors
+
+AgentsDock's original code is licensed under the Apache License, Version 2.0,
+except where a component explicitly states another license. See LICENSE.
+
+Third-party and separately licensed components retain their own copyrights,
+licenses, and attribution notices. In particular:
+
+- mobile-react/LICENSE preserves the Expo template's MIT license and
+  copyright notice for 650 Industries, Inc. (Expo).
+- The agentsdock-native-video, agentsdock-native-terminal, and
+  agentsdock-android-updater modules retain the MIT license declared in
+  their package metadata.
+- SwiftTerm retains its MIT license in
+  mobile-react/modules/agentsdock-native-terminal/ios/Vendor/SwiftTerm/LICENSE.
+
+Dependencies and other bundled third-party materials remain subject to their
+respective license terms. This notice does not replace those licenses.

package/README.md

@@ -0,0 +1,60 @@
+# @agentsdock/server
+
+AgentsDock's self-hosted server, distributed with its existing Python runtime
+installer. The desktop app remains a separate signed native download.
+
+This package has no installation lifecycle hooks. Installing the npm package
+does not start, stop, upgrade, or log into a server. The service runs from its
+own versioned installation directory, never from an npm or npx cache.
+
+## First installation
+
+This opt-in beta is for testing fresh installations. It does not enable
+automatic app-to-server updates or migrate existing installations. To install:
+
+```sh
+npx @agentsdock/server@beta install --port 7850
+```
+
+Use an exact package version for reproducible installations. The command needs
+the same prerequisites as the source installer: a trusted `uv`, Linux with a
+working user systemd session or Apple silicon macOS with a GUI launchd session,
+and the desired provider CLIs. It runs as the current user without `sudo`.
+
+The npm entrypoint only permits a fresh default installation. It refuses an
+existing managed installation, legacy service, or custom installation roots;
+changing directories does not create a second service. Use AgentsDock's managed
+update controls for an existing server. Multiple named services are not enabled
+by this package.
+
+## Managed updates
+
+The CLI also supports managed updates using a compatible running server and a
+separately reviewed, signed release descriptor. Existing-installation migration
+and recovery are outside this beta's fresh-install testing scope. The command
+binds its request to a known server and its current process instance:
+
+```sh
+agentsdock-server update --server-url https://server.example \
+  --server-identity ID --server-instance-id INSTANCE \
+  --token-file /private/path/server-token \
+  --manifest agents-server-npm-manifest.json \
+  --signature agents-server-npm-manifest.sig
+```
+
+The token file must be a current-user-owned regular file readable only by that
+user, containing the server token alone. HTTPS is required except for literal
+loopback addresses and localhost. Redirects are refused. The command checks the
+authenticated server identity, then submits the signed descriptor to its managed
+update endpoint. The server verifies the signature and waits for idle before
+activating an update. A pending response means scheduled, not installed. No
+registry tag, unsigned descriptor, or local installer bypasses this lifecycle.
+
+## Packaging
+
+The source `server/package.json` is deliberately private. Run
+`python3 server/scripts/package_npm_release.py --output dist/npm-server` from
+the repository root to stage only the audited runtime allowlist, stamp
+`server/VERSION`, and produce the publishable tarball plus its unsigned release
+descriptor. The manual preparation workflow signs that descriptor. This command
+does not publish to npm. Publish only a reviewed and verified prepared tarball.

package/npm/cli.cjs

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+'use strict'
+
+const fs = require('node:fs')
+const path = require('node:path')
+const os = require('node:os')
+const net = require('node:net')
+const crypto = require('node:crypto')
+const http = require('node:http')
+const https = require('node:https')
+const { spawnSync } = require('node:child_process')
+
+const HELP = `Usage: agentsdock-server install [--port PORT] [--bind IP] [--non-interactive] [--dry-run]
+       agentsdock-server recover
+       agentsdock-server update --server-url URL --server-identity ID --server-instance-id ID
+         --token-file PATH --manifest PATH --signature PATH
+       agentsdock-server --version
+
+install: fresh default user service only; existing installations must use managed updates.
+recover: on the server computer, recover an interrupted pre-activation migration; then retry the app update.
+update: verify the signed descriptor and request an update when the exact server is idle.
+No installation hooks run when this npm package is installed.
+`
+const ROOT_SELECTORS = ['AGENTS_SERVER_INSTALL_DIR', 'AGENTS_SERVER_CONFIG_DIR', 'AGENTS_SERVER_STATE_DIR', 'AGENTSDOCK_STATE_DIR', 'ZENITHBOT_AGENT_DIR', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME']
+
+function parse(argv) {
+  const [command = 'help', ...args] = argv
+  if (['help', '--help', '-h', '--version'].includes(command)) {
+    if (args.length) throw new Error('Unexpected arguments.')
+    return { command }
+  }
+  const values = command === 'install' ? ['--port', '--bind'] : command === 'update'
+    ? ['--server-url', '--server-identity', '--server-instance-id', '--token-file', '--manifest', '--signature'] : []
+  if (!['install', 'update', 'recover'].includes(command)) throw new Error('Use install, update, recover, or --help.')
+  const flags = command === 'install' ? ['--non-interactive', '--dry-run'] : []
+  const options = {}
+  for (let index = 0; index < args.length; index++) {
+    const name = args[index]
+    if (Object.hasOwn(options, name)) throw new Error(`Duplicate option: ${name}`)
+    if (flags.includes(name)) options[name] = true
+    else if (values.includes(name)) {
+      const value = args[++index]
+      if (!value || value.startsWith('--') || /[\x00-\x1f\x7f]/.test(value)) throw new Error(`Missing or invalid value for ${name}`)
+      options[name] = value
+    } else throw new Error(`Unsupported option: ${name}`)
+  }
+  if (command === 'update') for (const name of values) if (!options[name]) throw new Error(`Required option: ${name}`)
+  if (options['--port'] && (!/^[1-9][0-9]{0,4}$/.test(options['--port']) || Number(options['--port']) > 65535)) throw new Error('Port must be an integer from 1 to 65535.')
+  if (options['--bind'] && !net.isIP(options['--bind'])) throw new Error('Bind address must be a literal IP address.')
+  return { command, options }
+}
+
+function readRegular(filename, maxBytes, { privateFile = false, uid = process.getuid?.() } = {}) {
+  const descriptor = fs.openSync(filename, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0))
+  try {
+    const info = fs.fstatSync(descriptor)
+    if (!info.isFile() || info.size > maxBytes || info.nlink !== 1) throw new Error('Expected a bounded regular file.')
+    if (privateFile && (info.uid !== uid || (info.mode & 0o077) !== 0)) throw new Error('Token file must be owned by the current user and readable only by that user.')
+    const bytes = fs.readFileSync(descriptor)
+    if (bytes.length > maxBytes) throw new Error('File exceeded its size limit.')
+    return bytes
+  } finally { fs.closeSync(descriptor) }
+}
+
+function ensureFreshInstall(context) {
+  if (context.uid === 0) throw new Error('Run as the user who will own the server, without sudo.')
+  if (!['darwin', 'linux'].includes(context.platform)) throw new Error('Server installation requires Linux or Apple silicon macOS.')
+  for (const name of ROOT_SELECTORS) if (context.env[name]) throw new Error(`Custom installation selector ${name} is unsupported by the fresh-install CLI. Use the existing server's managed updater.`)
+  const existingInstall = () => new Error('An existing server installation or state was found. Use AgentsDock or agentsdock-server update; no installer was started.')
+  const safeDirectory = info => info.isDirectory() && !info.isSymbolicLink() && info.uid === context.uid && (info.mode & 0o022) === 0 && (info.mode & 0o500) === 0o500
+  const allowEmptyScaffold = (relative, child) => {
+    const root = path.join(context.home, relative)
+    let rootInfo
+    try { rootInfo = fs.lstatSync(root) } catch (error) { if (error.code !== 'ENOENT') throw error }
+    if (!rootInfo) return
+    // Failed bootstrap or preactivation can leave these exact empty directories.
+    // Never delete them or admit files, credentials, histories, links or locks.
+    // install.sh repeats this check under exclusive installation ownership.
+    if (!safeDirectory(rootInfo)) throw existingInstall()
+    const entries = fs.readdirSync(root)
+    if (entries.length > 1 || (entries.length === 1 && entries[0] !== child)) throw existingInstall()
+    if (entries.length === 1) {
+      const nested = path.join(root, child)
+      if (!safeDirectory(fs.lstatSync(nested)) || fs.readdirSync(nested).length !== 0) throw existingInstall()
+    }
+  }
+  allowEmptyScaffold('.local/share/agents-server', 'releases')
+  allowEmptyScaffold('.config/agents-server')
+  allowEmptyScaffold('.agentsdock', 'admin')
+  const targets = [
+    '.zenithbot-agent',
+    '.config/systemd/user/agents-server.service', '.config/systemd/user/zenithbot-agent.service',
+    'Library/LaunchAgents/com.agentsdock.server.plist',
+  ]
+  for (const relative of targets) {
+    try {
+      fs.lstatSync(path.join(context.home, relative))
+      throw existingInstall()
+    } catch (error) { if (error.code !== 'ENOENT') throw error }
+  }
+  if (context.platform === 'darwin') {
+    const check = context.spawn('/bin/launchctl', ['print', `gui/${context.uid}/com.agentsdock.server`], { encoding: 'utf8', timeout: 10000 })
+    if (check.status === 0) throw new Error('An AgentsServer service already exists. Use its managed updater.')
+    if (check.error || !/could not find service|service.*not found/i.test(`${check.stdout || ''} ${check.stderr || ''}`)) throw new Error('Could not verify the user service is absent. No installer was started.')
+  } else {
+    for (const unit of ['agents-server.service', 'zenithbot-agent.service']) {
+      const check = context.spawn('systemctl', ['--user', 'show', unit, '--property=LoadState', '--value'], { encoding: 'utf8', timeout: 10000 })
+      if (check.error || String(check.stdout).trim() !== 'not-found') throw new Error('An existing user service was found or its absence could not be verified. Use its managed updater.')
+    }
+  }
+}
+
+function recoveryContext(context) {
+  if (context.uid === 0) throw new Error('Run as the user who owns the server, without sudo.')
+  if (!['darwin', 'linux'].includes(context.platform)) throw new Error('Server recovery requires Linux or Apple silicon macOS.')
+  for (const name of ROOT_SELECTORS) if (context.env[name]) throw new Error(`Custom installation selector ${name} is unsupported by recovery; no installer was started.`)
+  const inspect = filename => {
+    try { return fs.lstatSync(filename) } catch (error) { if (error.code !== 'ENOENT') throw error; return null }
+  }
+  const directory = (filename, { optional = false, privateDirectory = false } = {}) => {
+    const info = inspect(filename)
+    if (!info && optional) return null
+    if (!info || !info.isDirectory() || info.isSymbolicLink() || info.uid !== context.uid ||
+        (info.mode & (privateDirectory ? 0o077 : 0o022)) !== 0 || (info.mode & 0o500) !== 0o500) {
+      throw new Error('Recovery requires owned, unlinked, safely permissioned default installation directories.')
+    }
+    return info
+  }
+  const readPrivate = (filename, limit) => {
+    const fd = fs.openSync(filename, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK)
+    try {
+      const info = fs.fstatSync(fd)
+      if (!info.isFile() || info.uid !== context.uid || (info.mode & 0o077) !== 0 || info.nlink !== 1 || info.size > limit) {
+        throw new Error('Recovery requires a bounded, private, current-user-owned regular control file.')
+      }
+      const bytes = fs.readFileSync(fd)
+      if (bytes.length > limit) throw new Error('Recovery control file exceeded its size limit.')
+      return bytes
+    } finally { fs.closeSync(fd) }
+  }
+  directory(context.home)
+  let root = context.home
+  for (const component of ['.local', 'share', 'agents-server']) {
+    root = path.join(root, component)
+    if (!directory(root, { optional: true })) return null
+  }
+  const rootInfo = directory(root)
+  const journalDirectory = path.join(root, '.activation-transaction')
+  if (!directory(journalDirectory, { optional: true, privateDirectory: true })) return null
+  const journal = JSON.parse(readPrivate(path.join(journalDirectory, 'manifest.json'), 256 * 1024))
+  const origin = ['rolling-back', 'rolled-back', 'rollback-healthy'].includes(journal.phase) ? journal.rollback_from : journal.phase
+  const config = path.join(context.home, '.config/agents-server')
+  const state = path.join(context.home, '.agentsdock')
+  const service = context.platform === 'darwin' ? path.join(context.home, 'Library/LaunchAgents/com.agentsdock.server.plist') : path.join(context.home, '.config/systemd/user/agents-server.service')
+  if (journal.format !== 3 || !['prepared', 'guarded'].includes(origin) || journal.intent !== 'server-update' ||
+      !/^activation-[0-9a-f]{24}$/.test(journal.transaction_id) ||
+      !/^\d+\.\d+\.\d+(?:-beta\.[1-9]\d*)?$/.test(journal.release_version) ||
+      journal.release_dir !== path.join(root, 'releases', journal.release_version) ||
+      journal.env_path !== path.join(config, 'env') || journal.service_path !== service ||
+      journal.service_state !== 'running' || journal.execution?.gateway_state !== 'absent' ||
+      journal.execution?.runtime_dir !== path.join(state, 'execution') ||
+      !Number.isSafeInteger(journal.execution?.api_contract) || journal.execution.api_contract < 1 ||
+      journal.hub?.kind !== 'server-update' || journal.hub?.data_dir !== path.join(state, 'team-hub')) {
+    throw new Error('This journal is not a supported interrupted pre-activation migration; no installer was started.')
+  }
+  directory(state, { privateDirectory: true })
+  const identity = readPrivate(path.join(state, 'server-identity'), 1024).toString('utf8').trim()
+  if (!/^[A-Za-z0-9_.:-]{8,240}$/.test(identity) || journal.hub.host_identity !== identity) {
+    throw new Error('The pending migration belongs to a different server identity; no installer was started.')
+  }
+  // The installer validates complete native configuration, links, ownership and
+  // authenticated incumbent health under its lock. These checks only select
+  // the exact existing transaction; they never grant recovery authority.
+  const ownerParent = path.join(root, '.activation-recovery')
+  if (directory(ownerParent, { optional: true, privateDirectory: true }) && inspect(path.join(ownerParent, journal.transaction_id))) {
+    throw new Error('This activation already has a recovery owner; no competing recovery was started.')
+  }
+  return { root, rootInfo, journalDirectory, journal, identity }
+}
+
+function validateOrigin(value) {
+  const url = new URL(value)
+  if (url.username || url.password || url.search || url.hash || !['', '/'].includes(url.pathname)) throw new Error('Server URL must be an origin without credentials, path, query, or fragment.')
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) throw new Error('Use HTTPS for remote servers; HTTP is allowed only on loopback.')
+  return url.origin
+}
+
+async function requestJSON(context, url, token, body) {
+  // Native admin routes intentionally reject browser transport headers. Node's
+  // fetch adds Sec-Fetch-Mode, so use the native HTTP client without redirects.
+  const payload = body ? Buffer.from(JSON.stringify(body)) : null
+  return new Promise((resolve, reject) => {
+    let deadline
+    const fail = error => { clearTimeout(deadline); reject(error) }
+    const finish = value => { clearTimeout(deadline); resolve(value) }
+    const send = context.request || (url.startsWith('https:') ? https.request : http.request)
+    const request = send(url, {
+      method: body ? 'POST' : 'GET',
+      headers: { 'X-AgentsDock-Token': token, ...(payload ? { 'Content-Type': 'application/json', 'Content-Length': payload.length } : {}) },
+    }, response => {
+      if (response.statusCode < 200 || response.statusCode >= 300) {
+        response.destroy()
+        fail(new Error(`Server request failed (HTTP ${response.statusCode}); no installer fallback was attempted.`))
+        return
+      }
+      const chunks = []
+      let size = 0
+      response.on('data', chunk => {
+        size += chunk.length
+        if (size > 1024 * 1024) { request.destroy(new Error('Server response exceeded its size limit.')); return }
+        chunks.push(chunk)
+      })
+      response.on('error', fail)
+      response.on('end', () => {
+        try { finish(JSON.parse(Buffer.concat(chunks).toString('utf8'))) } catch { fail(new Error('Server returned invalid JSON.')) }
+      })
+    })
+    request.on('error', fail)
+    deadline = setTimeout(() => request.destroy(new Error('Server request timed out.')), 30000)
+    deadline.unref()
+    request.setTimeout(30000, () => request.destroy(new Error('Server request timed out.')))
+    request.end(payload)
+  })
+}
+
+async function run(argv, overrides = {}) {
+  const context = { env: process.env, home: os.homedir(), uid: process.getuid?.(), platform: process.platform, spawn: spawnSync, packageRoot: path.resolve(__dirname, '..'), print: text => process.stdout.write(`${text}\n`), ...overrides }
+  const { command, options } = parse(argv)
+  if (['help', '--help', '-h'].includes(command)) { context.print(HELP); return 0 }
+  const metadata = JSON.parse(readRegular(path.join(context.packageRoot, 'package.json'), 64000))
+  if (command === '--version') { context.print(metadata.version); return 0 }
+  const payload = path.join(context.packageRoot, 'server')
+  const payloadVersion = readRegular(path.join(payload, 'VERSION'), 200).toString('utf8').trim()
+  if (payloadVersion !== metadata.version) throw new Error('Package and server payload versions do not match.')
+  if (command === 'recover') {
+    const recovery = recoveryContext(context)
+    if (!recovery) { context.print('No unfinished default server migration was found. No changes were made.'); return 0 }
+    const installer = path.join(payload, 'install.sh')
+    readRegular(installer, 2 * 1024 * 1024)
+    const args = [installer, '--recover-only', '--recover-unarmed-only', '--non-interactive', '--execution-mode', 'split',
+      '--expected-activation-id', recovery.journal.transaction_id, '--release-version', recovery.journal.release_version,
+      '--expected-api-contract', String(recovery.journal.execution.api_contract), '--expected-server-identity', recovery.identity]
+    const env = { HOME: context.home }
+    for (const key of ['PATH', 'USER', 'LOGNAME', 'SHELL', 'TMPDIR', 'LANG', 'LC_ALL', 'TERM', 'TERMINFO', 'SSL_CERT_FILE', 'SSL_CERT_DIR']) {
+      if (context.env[key]) env[key] = context.env[key]
+    }
+    const result = context.spawn('/bin/bash', args, { stdio: 'inherit', env })
+    if (result.error) throw new Error('Could not launch the bundled recovery installer.')
+    if (![0, 75].includes(result.status)) return Number.isInteger(result.status) ? result.status : 1
+    const rootAfter = fs.lstatSync(recovery.root)
+    if (!rootAfter.isDirectory() || rootAfter.isSymbolicLink() || rootAfter.dev !== recovery.rootInfo.dev || rootAfter.ino !== recovery.rootInfo.ino) {
+      throw new Error('Installation ownership changed during recovery; verify the server before retrying.')
+    }
+    try { fs.lstatSync(recovery.journalDirectory); throw new Error('The activation journal remains; recovery is not complete.') } catch (error) { if (error.code !== 'ENOENT') throw error }
+    context.print('The interrupted migration was recovered. Reconnect to AgentsDock and retry the update; the server has not been upgraded by this command.')
+    return 0
+  }
+  if (command === 'install') {
+    ensureFreshInstall(context)
+    const installer = path.join(payload, 'install.sh')
+    readRegular(installer, 2 * 1024 * 1024)
+    const args = [installer, '--fresh-install-only', '--release-version', metadata.version]
+    for (const name of ['--port', '--bind']) if (options[name]) args.push(name, options[name])
+    if (options['--non-interactive']) args.push('--non-interactive')
+    if (options['--dry-run']) { context.print(JSON.stringify({ command: '/bin/bash', args, executed: false })); return 0 }
+    const result = context.spawn('/bin/bash', args, { stdio: 'inherit', env: context.env })
+    if (result.error) throw new Error('Could not launch the bundled installer.')
+    return Number.isInteger(result.status) ? result.status : 1
+  }
+  const origin = validateOrigin(options['--server-url'])
+  for (const name of ['--server-identity', '--server-instance-id']) if (!/^[A-Za-z0-9_.:-]{1,128}$/.test(options[name])) throw new Error('Invalid expected server identity.')
+  const manifest = readRegular(options['--manifest'], 8192)
+  const signature = readRegular(options['--signature'], 64)
+  const publicKey = readRegular(path.join(payload, 'release-public-key.pem'), 4096)
+  if (signature.length !== 64 || !crypto.verify(null, manifest, publicKey, signature)) throw new Error('Release descriptor signature is invalid.')
+  const descriptor = JSON.parse(manifest)
+  if (descriptor.schema !== 2 || descriptor.distribution !== 'npm' || descriptor.npm?.name !== '@agentsdock/server') throw new Error('Expected a signed npm server release descriptor.')
+  const token = readRegular(options['--token-file'], 4096, { privateFile: true, uid: context.uid }).toString('utf8').trim()
+  if (!token || /[\x00-\x20\x7f]/.test(token)) throw new Error('Token file must contain one nonempty server token.')
+  const identity = { expected_server_identity: options['--server-identity'], expected_server_instance_id: options['--server-instance-id'] }
+  const health = await requestJSON(context, `${origin}/api/health`, token)
+  if (health.server_identity !== identity.expected_server_identity || health.server_instance_id !== identity.expected_server_instance_id) throw new Error('The connected server or its process instance changed. No update was requested.')
+  const result = await requestJSON(context, `${origin}/api/admin/update/ensure`, token, { ...identity, manifest_base64: manifest.toString('base64'), signature_base64: signature.toString('base64') })
+  context.print(JSON.stringify(result, null, 2))
+  return 0
+}
+
+if (require.main === module) run(process.argv.slice(2)).then(code => { process.exitCode = code }).catch(error => { process.stderr.write(`agentsdock-server: ${error.message}\n`); process.exitCode = 1 })
+module.exports = { parse, readRegular, ensureFreshInstall, recoveryContext, validateOrigin, run }

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@agentsdock/server",
+  "version": "1.0.7-beta.5",
+  "description": "AgentsDock's self-hosted Python server and explicit installation CLI",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZhengyiLuo/AgentsDock.git",
+    "directory": "server"
+  },
+  "bin": {
+    "agentsdock-server": "npm/cli.cjs"
+  },
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "files": [
+    "npm/cli.cjs",
+    "server/",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}