appback-remoteagent 0.15.4 → 0.15.5

package/dist/bot.js

@@ -2258,6 +2258,9 @@ print(text)
     const preview = stdout.trim();
     return preview || undefined;
 }
+const TELEGRAM_FILE_DOWNLOAD_ATTEMPTS = 4;
+const TELEGRAM_FILE_DOWNLOAD_TIMEOUT_SECONDS = 120;
+const TELEGRAM_FILE_DOWNLOAD_CONNECT_TIMEOUT_SECONDS = 20;
 async function downloadTelegramFile(botToken, botId, chatId, fileId, preferredName) {
     const file = await callTelegramApi(botToken, "getFile", {
         file_id: fileId,
@@ -2270,20 +2273,43 @@ async function downloadTelegramFile(botToken, botId, chatId, fileId, preferredNa
     const extension = path.extname(file.file_path) || path.extname(preferredName ?? "") || ".bin";
     const basename = path.basename(preferredName ?? file.file_path, path.extname(preferredName ?? file.file_path));
     const outputPath = path.join(directory, `${Date.now()}-${safePathSegment(basename)}-${randomUUID()}${extension}`);
+    const partialPath = `${outputPath}.part`;
     const fileUrl = new URL(file.file_path, `https://api.telegram.org/file/bot${botToken}/`).toString();
-    const { stderr } = await execFileAsync("curl", [
-        "-fL",
-        "-sS",
-        "--max-time",
-        "60",
-        "-o",
-        outputPath,
-        fileUrl,
-    ]);
-    if (stderr?.trim()) {
-        console.error(`curl stderr for Telegram file download: ${stderr.trim()}`);
+    let lastError;
+    for (let attempt = 1; attempt <= TELEGRAM_FILE_DOWNLOAD_ATTEMPTS; attempt += 1) {
+        try {
+            const { stderr } = await execFileAsync("curl", [
+                "-fL",
+                "-sS",
+                "--connect-timeout",
+                String(TELEGRAM_FILE_DOWNLOAD_CONNECT_TIMEOUT_SECONDS),
+                "--max-time",
+                String(TELEGRAM_FILE_DOWNLOAD_TIMEOUT_SECONDS),
+                "-C",
+                "-",
+                "-o",
+                partialPath,
+                fileUrl,
+            ]);
+            if (stderr?.trim()) {
+                console.error(`curl stderr for Telegram file download: ${stderr.trim()}`);
+            }
+            await fs.rename(partialPath, outputPath);
+            return { path: outputPath };
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < TELEGRAM_FILE_DOWNLOAD_ATTEMPTS) {
+                const partialSize = await fs.stat(partialPath).then((stat) => stat.size).catch(() => 0);
+                console.error(`Telegram file download attempt ${attempt}/${TELEGRAM_FILE_DOWNLOAD_ATTEMPTS} failed; ` +
+                    `retrying with resume from ${partialSize} bytes.`);
+                await sleep(Math.min(5000, attempt * 1000));
+                continue;
+            }
+        }
     }
-    return { path: outputPath };
+    await fs.rm(partialPath, { force: true }).catch(() => undefined);
+    throw lastError instanceof Error ? lastError : new Error("Telegram file download failed.");
 }
 function safePathSegment(value) {
     const safe = value.replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/^_+|_+$/g, "");

package/docs/OPERATIONS.md

@@ -11,6 +11,7 @@ RemoteAgent production is operated from one canonical Git history:
 
 Do not treat stale server paths or duplicate worktrees as authoritative.
 Code changes should be committed and pushed to `origin/main`, published to npm, and then server 30/26 should be updated from that npm version.
+Installing a local tarball directly on a server is an emergency hotfix only; it is not a completed production release until the same version is published to npm and both targets are reconciled to that npm version.
 
 ## Product shape in operations
 
@@ -134,6 +135,7 @@ If a temporary branch is unavoidable, merge it back to `main`, push it, and depl
 
 A task is not done until commit and push both happened.
 A production deployment is not done until server 30 and server 26 are running the published npm version and the runtime path has been verified.
+If npm publish fails with `403`, do not keep retrying or switch to source deployment. Confirm the npm token has publish rights for the unscoped `appback-remoteagent` package, then publish. See `docs/RELEASING.md`.
 
 See `docs/RELEASING.md` for the detailed versioning rules.
 

package/docs/RELEASING.md

@@ -28,7 +28,7 @@ A release is only considered complete when all of the following are done in orde
 4. Run `npm run build`
 5. Commit the completed work
 6. Push `main` to `origin/main`
-7. Publish `appback-remoteagent@<version>` to npm from server 30's npm credentials
+7. Publish `appback-remoteagent@<version>` to npm using a token/account that is proven to have publish rights for this unscoped package
 8. Install that exact npm version on server 30 and server 26
 9. Restart `remoteagent.service` on each target if runtime code changed
 10. Verify the relevant runtime path, logs, or Telegram behavior on each target
@@ -71,27 +71,74 @@ npm pack
 
 Use this package-specific path for `appback-remoteagent`.
 
-Do not publish this package from machine 21 with the `21token`. That token is scoped for `@appbackhub` packages and cannot publish the unscoped `appback-remoteagent` package. It can authenticate but `npm publish` fails with:
+Direct `npm publish` is blocked by `prepublishOnly`.
+The only normal publish command is:
+
+```bash
+npm run release:publish
+```
+
+Do not publish this package with the machine 21 `21token`.
+That token can authenticate as `appbackhub`, but it does not currently have publish rights for the unscoped `appback-remoteagent` package.
+It fails at publish time with:
 
 ```text
 403 Forbidden - You may not perform that action with these credentials.
 ```
 
-The successful publish path is:
+Before publishing, always verify both identity and package ownership:
 
 ```bash
-VERSION=0.14.0
-npm pack
-scp appback-remoteagent-$VERSION.tgz au2223@192.168.0.30:/tmp/appback-remoteagent-$VERSION.tgz
-ssh au2223@192.168.0.30 "bash -lc 'npm publish /tmp/appback-remoteagent-$VERSION.tgz'"
+npm whoami
+npm owner ls appback-remoteagent
+```
+
+Authentication alone is not enough.
+If `npm whoami` works but `npm publish` returns `403`, stop and get a publish-capable npm token instead of retrying with the same token.
+
+The guarded registry publish path is:
+
+```bash
+npm run release:publish
 npm view appback-remoteagent version
-ssh au2223@192.168.0.30 'bash -lc "npm view appback-remoteagent version"'
-rm -f appback-remoteagent-$VERSION.tgz
-ssh au2223@192.168.0.30 "rm -f /tmp/appback-remoteagent-$VERSION.tgz"
 ```
 
 If registry caching briefly returns the previous version after publish, wait a few seconds and rerun `npm view appback-remoteagent version` before installing to servers.
 
+## Emergency tarball install
+
+An emergency tarball install is allowed only to restore a broken runtime when npm publish is blocked.
+It is not a completed release and must be reported as a temporary hotfix.
+
+Rules:
+
+- do not call it "npm deployed" or "released"
+- do not delete runtime state
+- do not use source checkout deployment
+- confirm no active provider process is running before restart
+- install the exact local package tarball with `npm install -g /tmp/appback-remoteagent-<version>.tgz`
+- follow up by publishing the same version to npm once a publish-capable token is available
+
+Emergency server 30 flow:
+
+```bash
+VERSION=0.14.0
+npm pack
+scp appback-remoteagent-$VERSION.tgz au2223@192.168.0.30:/tmp/
+ssh au2223@192.168.0.30 "VERSION=$VERSION bash -s" <<'REMOTE'
+set -euo pipefail
+export PATH="/home/au2223/.local/bin:/home/au2223/.nvm/versions/node/v22.22.0/bin:$PATH"
+pgrep -af 'codex|claude' || true
+npm install -g "/tmp/appback-remoteagent-$VERSION.tgz"
+remoteagent-install
+sudo -n systemctl restart remoteagent
+systemctl is-active remoteagent
+node -p 'require("/home/au2223/.nvm/versions/node/v22.22.0/lib/node_modules/appback-remoteagent/package.json").version'
+journalctl -u remoteagent --since '2 minutes ago' --no-pager
+REMOTE
+rm -f appback-remoteagent-$VERSION.tgz
+```
+
 ## Target deployment sequence
 
 Server 30 uses a systemd service:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appback-remoteagent",
-  "version": "0.15.4",
+  "version": "0.15.5",
   "description": "Personal installable session server for continuing local AI work across PC and Telegram",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,8 @@
     "check": "tsc --noEmit -p tsconfig.json",
     "selftest:telegram": "npm run build && node scripts/selftest-telegram-update.mjs",
     "prepare": "npm run build",
+    "prepublishOnly": "node scripts/prepublish-guard.mjs",
+    "release:publish": "bash scripts/release-publish.sh",
     "version:patch": "npm version --no-git-tag-version patch",
     "version:minor": "npm version --no-git-tag-version minor",
     "version:major": "npm version --no-git-tag-version major"

package/scripts/prepublish-guard.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+if (process.env.REMOTEAGENT_PUBLISH_GUARD_OK === "1") {
+  process.exit(0);
+}
+
+console.error([
+  "Direct npm publish is blocked for appback-remoteagent.",
+  "",
+  "Use the documented release path instead:",
+  "  npm run release:publish",
+  "",
+  "Reason:",
+  "- direct publish has repeatedly used the wrong npm token",
+  "- appback-remoteagent must be published only through the guarded script",
+  "- emergency tarball installs are not completed releases",
+].join("\n"));
+
+process.exit(1);

package/scripts/release-publish.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+PACKAGE_NAME="$(node -p 'require("./package.json").name')"
+VERSION="$(node -p 'require("./package.json").version')"
+
+if [[ "$PACKAGE_NAME" != "appback-remoteagent" ]]; then
+  echo "Unexpected package name: $PACKAGE_NAME" >&2
+  exit 1
+fi
+
+if [[ -n "$(git status --porcelain)" ]]; then
+  echo "Working tree is not clean. Commit and push before publishing." >&2
+  git status --short >&2
+  exit 1
+fi
+
+echo "Publishing $PACKAGE_NAME@$VERSION"
+echo
+echo "npm identity:"
+npm whoami
+echo
+echo "npm owners:"
+npm owner ls "$PACKAGE_NAME"
+echo
+
+npm run check
+npm run build
+
+TARBALL="$(npm pack --silent)"
+cleanup() {
+  rm -f "$TARBALL"
+}
+trap cleanup EXIT
+
+echo
+echo "Publishing tarball: $TARBALL"
+REMOTEAGENT_PUBLISH_GUARD_OK=1 npm publish "$TARBALL" --access public
+
+echo
+echo "Verifying registry version:"
+npm view "$PACKAGE_NAME" version