@delta-agentcloud/cli 1.1.30 → 1.1.34

package/README.md

@@ -281,7 +281,7 @@ delta-cli sandbox operation <request_id>
 | `delta-cli sandbox run-bg <id> --command "..." [--timeout <sec>] [--wait] [--cancel-on-timeout] [--format sse\|json] [--json-result] [--summary/--no-summary] [--artifacts]` | Run a command in the background; without `--wait` it returns `{execution_id, sandbox_id}` immediately (with `--format json`, the unified result object with `finished=false`); with `--wait` it follows via SSE (raw `data:` frames to stdout, no trailing envelope); `--format json` prints exactly one envelope with the same structure as `sandbox run --format json`. **On a wait timeout** → `error.type=timeout` and a **non-zero** process exit code, with `error.details` keeping `sandbox_id`/`execution_id`/`remote_state` (`not_cancelled`/`cancelled`/`cancel_failed`) so the command can be queried or cancelled afterwards; `remote_state=not_cancelled` means only the local wait stopped and **the remote command may still be running**. The remote command is left running by default — add `--cancel-on-timeout` to cancel it (a failed cancel is reported as `cancel_failed`) |
 | `delta-cli sandbox logs <id> --execution-id <eid> [--tail N --grep <pattern> --context N --max-bytes N]` | Show background logs; returns `stderr_size + stderr_tail` by default (avoids context blow-up); filter with `--tail/--grep` |
 | `delta-cli sandbox cancel <id> --execution-id <eid>` | Interrupt a background command |
-| `delta-cli sandbox read <id> --path <path> [--output <local path>] [--tail N] [--grep <pattern>] [--offset N] [--limit N] [--context N] [--max-bytes N] [--parse-json]` | Read a file in the container; `--output <path>` saves locally; filter with `--tail/--grep`. **A full copy (without `--tail/--grep/--offset/--limit/--max-bytes`) is byte-exact**: it goes through the chunked download path (binary-safe, sha256-verified — the envelope reports `byte_exact:true`, `integrity:"sha256"`, `digest_verified`); with any range filter it falls back to the text channel, where the server decodes as UTF-8 and replaces invalid bytes with U+FFFD, so the envelope then reports `byte_exact:false` / `integrity:"text_decoded"` and a warning is printed to stderr — **use `sandbox pull` to copy a binary file**. When the result is printed inline and the file is not valid UTF-8, `content` is the lossy text and the **exact original bytes** are in `content_base64` (base64-decode it); the envelope is marked `byte_exact:true`. Text files carry no `content_base64` |
+| `delta-cli sandbox read <id> --path <path> [--output <local path>] [--tail N] [--grep <pattern>] [--offset N] [--limit N] [--context N] [--max-bytes N] [--parse-json]` | Read a file in the container; `--output <path>` saves it locally; `--tail`/`--grep` filter the output. **A full copy (no `--tail`/`--grep`/`--offset`/`--limit`/`--max-bytes`) is byte-exact**: it goes through the chunked download path (binary-safe, sha256-verified — the envelope reports `byte_exact:true`, `integrity:"sha256"`, `digest_verified`). With a range filter the filter is applied to the **exact bytes**, so the copy is a byte-exact slice of the original (`byte_exact:true`, `integrity:"sha1"`). Printed inline, a text file gives `content` (strictly decoded, `byte_exact:true`) while a **non-UTF-8 file gives no `content` at all** — the exact original bytes are in `content_base64` (base64-decode it) and the envelope is marked `byte_exact:true`. Only a server that does not support that negotiation returns the lossy text (`integrity:"text_decoded"`, with a warning on stderr). |
 | `delta-cli sandbox pull <id> --source <sandbox path> --target <local path> [--pattern <glob>] [--concurrency N] [--no-resume] [--no-verify]` | Pull files/dirs from the sandbox to local (mirror of `upload`; flag direction reversed: source=remote, target=local). **Directories are always pulled recursively** (`--recursive` is deprecated and no longer needed); the transfer uses the **chunked download** path: binary-safe, end-to-end **sha256** verified (`digest_verified`), **resumable** (a partial `<target>.delta.part` is reused), and **parallel** across files and chunks (`--concurrency`, default 4) — so a large file is not bound by a single command timeout. The server publishes its limits with every response (`limits`): 4 MiB chunks (16 MiB max), 100 GiB max per file, 120 s per chunk, 600 s for the whole-file digest. `--no-resume` ignores a leftover `.delta.part`; `--no-verify` skips the sandbox-side sha256 comparison. **The payload moves as raw bytes** (the server's binary endpoint, so it is not inflated by base64; older servers fall back automatically), and **the chunks must tile the whole file**: a gap or an interrupted transfer is reported as a failure, never as a successful download |
 | `delta-cli sandbox write <id> --path <path> --source <local path>` | Write a file. **Binary-safe**: the content travels as raw bytes (the server's binary endpoint, with a base64 fallback for older servers) and the CLI declares its `size`/`sha256`, which the server verifies before writing (a mismatch is rejected); the response carries `server_sha256`/`sha256`/`size`/`size_verified`. A `--source` above 32 MiB goes through the streaming upload path instead of being read into memory |
 | `delta-cli sandbox write-multiple <id> --entry <remote path>=<local path>` | Write multiple files |

package/checksums.txt

@@ -1,5 +1,5 @@
-643aa677f4597ffeca3e96dd87ae2a002355b65e8a51d3be691da4484db6a66b  delta-cli-darwin-amd64.tar.gz
-fbc08c3e7d20830d33afbdd63f1d21d926b9220573afa2a39beb35d3ec8687d5  delta-cli-darwin-arm64.tar.gz
-e2c3e8c78f9b7aebb565bd3680ff948c6362cd9d884f7f34169f0397d4c1402f  delta-cli-linux-amd64.tar.gz
-1475959a99dbc0b7d47385ef1162ac41b1d696bf7ec128b22eefc865e9c21303  delta-cli-linux-arm64.tar.gz
-0dbdc5ca2a2706befde271cbb0077c48810a81aa68abd759344d415b41c36e6f  delta-cli-windows-amd64.zip
+492db2e329de38d28486a7df310bd0223c6bbcd465423d823b945b046a3a9173  delta-cli-darwin-amd64.tar.gz
+f0000cae8dfdeafcb33aa6716c38fcaa38219883a2439d0ee27a9425dd81651d  delta-cli-darwin-arm64.tar.gz
+7fff0a38b42c2694a37bb9415ebed791f70e3f41d8fde24670824ad5b7f56182  delta-cli-linux-amd64.tar.gz
+1ef7e3c95d6c44bb59e0d8b7c66258686fa85426e6f5fc298d406b1b4b9bbee6  delta-cli-linux-arm64.tar.gz
+68db2c20c6bb2127a2c6c8beecb383f362c5fbb7ca577df62392aea69c62f039  delta-cli-windows-amd64.zip

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delta-agentcloud/cli",
-  "version": "1.1.30",
+  "version": "1.1.34",
   "description": "Delta Agent Cloud CLI for sandbox compute and science tools.",
   "bin": {
     "delta-cli": "scripts/run.js"

package/scripts/install.js

@@ -9,23 +9,38 @@ const crypto = require("crypto");
 
 const PKG = "@delta-agentcloud/cli";
 
-// Resolve the version to download:
-//   env var > npm registry > local package.json (fallback)
-function resolveVersion() {
-  if (process.env.DELTA_CLI_VERSION) return process.env.DELTA_CLI_VERSION.replace(/^v/, "");
-  try {
-    const out = require("child_process").execFileSync("npm", ["view", PKG, "version"], {
-      stdio: ["ignore", "pipe", "pipe"],
-      timeout: 15000,
-      encoding: "utf8",
-    });
-    const ver = out.trim();
-    if (/^\d+\.\d+\.\d+/.test(ver)) return ver;
-  } catch {}
-  return require("../package.json").version.replace(/-.*$/, "");
-}
+  // The version of the package npm is installing. Its bundled checksums.txt is
+  // the only checksum source a mirror cannot tamper with, so the downloaded
+  // asset and the expected checksum always have to describe the same version.
+  const PACKAGED_VERSION = require("../package.json").version.replace(/-.*$/, "");
+
+  // The newest version the registry knows about. Used as a fallback when the
+  // packaged version has no matching release.
+  function registryLatestVersion() {
+    try {
+      const out = require("child_process").execFileSync("npm", ["view", PKG, "version"], {
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 15000,
+        encoding: "utf8",
+      });
+      const ver = out.trim();
+      if (/^\d+\.\d+\.\d+/.test(ver)) return ver;
+    } catch {}
+    return null;
+  }
 
-const VERSION = resolveVersion();
+  // Resolve the version to download:
+  //   env var > the packaged version > npm registry (fallback)
+  function resolveVersion() {
+    if (process.env.DELTA_CLI_VERSION) return process.env.DELTA_CLI_VERSION.replace(/^v/, "");
+    // The packaged version is what the user asked npm to install. Resolving to
+    // the registry's "latest" instead downloads the newest asset and verifies it
+    // against this package's older checksums.txt, which can never match.
+    if (PACKAGED_VERSION) return PACKAGED_VERSION;
+    return registryLatestVersion() || PACKAGED_VERSION;
+  }
+
+  const VERSION = resolveVersion();
 const NAME = "delta-cli";
 const REPO = "delta-agentcloud/delta-cli";
 const DEFAULT_ALLOWED_HOSTS = new Set([
@@ -283,14 +298,7 @@ function extractZipWindows(archivePath, destDir) {
 
 // ── Checksum ───────────────────────────────────────────────────────────────
 
-function getExpectedChecksum(archiveName, checksumsDir) {
-  const dir = checksumsDir || path.join(__dirname, "..");
-  const checksumsPath = path.join(dir, "checksums.txt");
-  if (!fs.existsSync(checksumsPath)) {
-    console.error("[WARN] checksums.txt not found, skipping checksum verification");
-    return null;
-  }
-  const content = fs.readFileSync(checksumsPath, "utf8");
+function parseChecksums(content, archiveName) {
   for (const line of content.split("\n")) {
     const trimmed = line.trim();
     if (!trimmed) continue;
@@ -303,6 +311,45 @@ function getExpectedChecksum(archiveName, checksumsDir) {
   throw new Error(`Checksum entry not found for ${archiveName}`);
 }
 
+function getExpectedChecksum(archiveName, checksumsDir) {
+  const dir = checksumsDir || path.join(__dirname, "..");
+  const checksumsPath = path.join(dir, "checksums.txt");
+  if (!fs.existsSync(checksumsPath)) {
+    console.error("[WARN] checksums.txt not found, skipping checksum verification");
+    return null;
+  }
+  return parseChecksums(fs.readFileSync(checksumsPath, "utf8"), archiveName);
+}
+
+// The canonical URL of one file inside a release, optionally through the
+// configured mirror.
+function releaseFileUrl(version, name) {
+  const url = "https://github.com/" + REPO + "/releases/download/v" + version + "/" + name;
+  const mirror = process.env.DELTA_CLI_MIRROR || "";
+  if (mirror) return mirror.replace(/\/$/, "") + "/" + url;
+  return url;
+}
+
+// The checksum of the release that is actually being downloaded. The bundled
+// checksums.txt only describes the packaged version, so any other version has
+// to bring its own checksums.txt from that same release.
+function expectedChecksumFor(version, archiveName, tmpDir) {
+  if (version === PACKAGED_VERSION) return getExpectedChecksum(archiveName);
+  const dest = path.join(tmpDir, "checksums-" + version + ".txt");
+  try {
+    download(releaseFileUrl(version, "checksums.txt"), dest);
+  } catch (e) {
+    console.error("[WARN] could not fetch checksums for v" + version + ": " + e.message + " — skipping checksum verification");
+    return null;
+  }
+  try {
+    return parseChecksums(fs.readFileSync(dest, "utf8"), archiveName);
+  } catch (e) {
+    console.error("[WARN] " + e.message + " — skipping checksum verification");
+    return null;
+  }
+}
+
 function verifyChecksum(archivePath, expectedHash) {
   if (expectedHash === null) return;
   const hash = crypto.createHash("sha256");
@@ -326,66 +373,85 @@ function verifyChecksum(archivePath, expectedHash) {
 
 // ── Main install ───────────────────────────────────────────────────────────
 
+function extractAndInstall(tmpDir, archivePath) {
+  try {
+    if (isWindows) {
+      console.error("Extracting archive...");
+      extractZipWindows(archivePath, tmpDir);
+    } else {
+      console.error("Extracting archive...");
+      execFileSync("tar", ["-xzf", archivePath, "-C", tmpDir], { stdio: "ignore" });
+    }
+
+    const binaryName = NAME + (isWindows ? ".exe" : "");
+    const extractedBinary = path.join(tmpDir, NAME + "-" + platform + "-" + arch);
+    if (fs.existsSync(extractedBinary)) {
+      fs.copyFileSync(extractedBinary, dest);
+    } else {
+      // Fallback: try the plain name (older release format)
+      const plainBinary = path.join(tmpDir, binaryName);
+      if (fs.existsSync(plainBinary)) {
+        fs.copyFileSync(plainBinary, dest);
+      } else {
+        // Search in tmpDir
+        const files = fs.readdirSync(tmpDir).filter(function(f) { return f.indexOf(NAME) !== -1 || f.indexOf(binaryName) !== -1; });
+        if (files.length > 0) {
+          fs.copyFileSync(path.join(tmpDir, files[0]), dest);
+        } else {
+          throw new Error("Binary not found in extracted archive. Files: " + fs.readdirSync(tmpDir).join(", "));
+        }
+      }
+    }
+    fs.chmodSync(dest, 0o755);
+    ensureExecutable(path.join(__dirname, "run.js"));
+    console.error("Installed to " + dest);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
 function install() {
   fs.mkdirSync(binDir, { recursive: true });
   var tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "delta-cli-"));
   var archivePath = path.join(tmpDir, archiveName);
 
-  releaseAssetUrls(VERSION, archiveName, function(downloadUrls) {
-    try {
+  // The packaged version first; the registry's latest is a fallback for a
+  // package whose version has no matching release.
+  var candidates = [VERSION];
+  var latest = registryLatestVersion();
+  if (latest && latest !== VERSION) candidates.push(latest);
+
+  var vi = 0;
+  function tryNextVersion() {
+    if (vi >= candidates.length) {
+      console.error("[FAIL] delta-cli could not be installed from any source");
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+      process.exit(1);
+    }
+    var version = candidates[vi++];
+    releaseAssetUrls(version, archiveName, function(downloadUrls) {
       var lastErr;
-      var downloaded = false;
       for (var i = 0; i < downloadUrls.length; i++) {
         try {
           console.error("Downloading from " + downloadUrls[i]);
           download(downloadUrls[i], archivePath);
           console.error("Download complete, verifying checksum...");
-          const expectedHash = getExpectedChecksum(archiveName);
+          const expectedHash = expectedChecksumFor(version, archiveName, tmpDir);
           verifyChecksum(archivePath, expectedHash);
           console.error("Checksum verified");
-          downloaded = true;
-          break;
+          extractAndInstall(tmpDir, archivePath);
+          return;
         } catch (e) {
           console.error("Failed: " + e.message + " (" + downloadUrls[i] + ")");
           lastErr = e;
         }
       }
-      if (!downloaded) throw lastErr;
-
-      if (isWindows) {
-        console.error("Extracting archive...");
-        extractZipWindows(archivePath, tmpDir);
-      } else {
-        console.error("Extracting archive...");
-        execFileSync("tar", ["-xzf", archivePath, "-C", tmpDir], { stdio: "ignore" });
-      }
+      console.error("Version v" + version + " could not be installed: " + (lastErr ? lastErr.message : "no source responded"));
+      tryNextVersion();
+    });
+  }
 
-      const binaryName = NAME + (isWindows ? ".exe" : "");
-      const extractedBinary = path.join(tmpDir, NAME + "-" + platform + "-" + arch);
-      if (fs.existsSync(extractedBinary)) {
-        fs.copyFileSync(extractedBinary, dest);
-      } else {
-        // Fallback: try the plain name (older release format)
-        const plainBinary = path.join(tmpDir, binaryName);
-        if (fs.existsSync(plainBinary)) {
-          fs.copyFileSync(plainBinary, dest);
-        } else {
-          // Search in tmpDir
-          const files = fs.readdirSync(tmpDir).filter(function(f) { return f.indexOf(NAME) !== -1 || f.indexOf(binaryName) !== -1; });
-          if (files.length > 0) {
-            fs.copyFileSync(path.join(tmpDir, files[0]), dest);
-          } else {
-            throw new Error("Binary not found in extracted archive. Files: " + fs.readdirSync(tmpDir).join(", "));
-          }
-        }
-      }
-      fs.chmodSync(dest, 0o755);
-      ensureExecutable(path.join(__dirname, "run.js"));
-      console.error("Installed to " + dest);
-    } finally {
-      fs.rmSync(tmpDir, { recursive: true, force: true });
-    }
-  });
+  tryNextVersion();
 }
 
 function ensureExecutable(filePath) {

package/skills/delta-sandbox/SKILL.md

@@ -174,7 +174,7 @@ The reason is that, after running a command, this skill reads `log_file` from th
 | List active tunnels | `sandbox exposes <id>` — list the public tunnels currently active for this sandbox |
 | Reclaim a tunnel | `sandbox dispose <id> --port N` — explicitly reclaim a single tunnel (stop frpc and release the public port); killing the sandbox also reclaims all its tunnels |
 | **File operations** | |
-| Read a file | `sandbox read <id> --path <path> [--output <local-path> --tail N --grep <pattern> --offset N --limit N --context N --max-bytes N --parse-json]` — **a full copy is byte-exact** (chunked download, sha256-verified); with `--tail`/`--grep`/`--offset`/`--limit` it uses the text channel and the envelope reports `byte_exact:false` — use `sandbox pull` for binary files. Printed inline, a non-UTF-8 file puts the **exact bytes** in `content_base64` (`content` is the lossy text) |
+| Read a file | `sandbox read <id> --path <path> [--output <local-path> --tail N --grep <pattern> --offset N --limit N --context N --max-bytes N --parse-json]` — **byte-exact**: a full copy goes through the chunked download (sha256-verified) and a filtered copy is a byte-exact slice of the original. Printed inline, a text file gives `content`; a **non-UTF-8 file gives no `content`** — the exact bytes are in `content_base64` |
 | Pull a file/directory | `sandbox pull <id> --source <sandbox-path> --target <local-path> [--pattern <glob>] [--concurrency N] [--no-resume] [--no-verify]` — pull a single file or **recursively** pull a directory (directories are always recursive), over the **chunked** path: bytes move verbatim (no base64 inflation), binary-safe, sha256-verified, resumable and parallel (the reverse of upload: source=remote, target=local) |
 | View the working directory | `sandbox working-directory <id>` (returns `data.path`, such as `/workspace/{user_id}/{sandbox_id}`) |
 | Write a file | `sandbox write <id> --source <filename>` (without `--path`, writes to the working directory by default); **every sandbox-side path** — `--path`, the remote part of `write-multiple --entry`, `upload --target`, `pull --source`, `run`/`run-bg --log-file` — is prefixed with the working directory when relative, while an absolute path is used as given. The content is **binary-safe** (raw bytes, with a base64 fallback for older servers) and the server verifies the declared `size`/`sha256` before writing, so the response's `server_sha256`/`size_verified` can be compared with the local file |

package/skills/delta-sandbox/references/commands.md

@@ -38,7 +38,7 @@
 
 | Command | Description |
 |------|------|
-| `sandbox read <id> --path <path> [--output <local-path>] [--tail N] [--grep <pattern>] [--offset N] [--limit N] [--context N] [--max-bytes N] [--parse-json]` | Read a file; returns `content` + `size` + `content_length`. `--output <path>` saves it locally; `--tail`/`--grep` filter the output. **A full copy (no `--tail`/`--grep`/`--offset`/`--limit`/`--max-bytes`) is byte-exact**: it goes through the chunked download path (binary-safe, sha256-verified — the envelope reports `byte_exact:true`, `integrity:"sha256"`, `digest_verified`). With any range filter it falls back to the text channel, where the server decodes as UTF-8 and replaces invalid bytes with U+FFFD; the envelope then reports `byte_exact:false` / `integrity:"text_decoded"` and a warning is printed to stderr. **Use `sandbox pull` to copy a binary file.** When the result is printed inline and the file is not valid UTF-8, `content` is the lossy text and the **exact original bytes** are in `content_base64` (base64-decode it); the envelope is marked `byte_exact:true`. Text files carry no `content_base64`. |
+| `sandbox read <id> --path <path> [--output <local-path>] [--tail N] [--grep <pattern>] [--offset N] [--limit N] [--context N] [--max-bytes N] [--parse-json]` | Read a file; returns `content` + `size` + `content_length`. `--output <path>` saves it locally; `--tail`/`--grep` filter the output. **A full copy (no `--tail`/`--grep`/`--offset`/`--limit`/`--max-bytes`) is byte-exact**: it goes through the chunked download path (binary-safe, sha256-verified — the envelope reports `byte_exact:true`, `integrity:"sha256"`, `digest_verified`). With a range filter the filter is applied to the **exact bytes**, so the copy is a byte-exact slice of the original (`byte_exact:true`, `integrity:"sha1"`). Printed inline, a text file gives `content` (strictly decoded, `byte_exact:true`) while a **non-UTF-8 file gives no `content` at all** — the exact original bytes are in `content_base64` (base64-decode it) and the envelope is marked `byte_exact:true`. Only a server that does not support that negotiation returns the lossy text (`integrity:"text_decoded"`, with a warning on stderr). |
 | `sandbox working-directory <id>` | Get the sandbox's current working directory (absolute path `/workspace/{user_id}/{sandbox_id}`). |
 | `sandbox write <id> [--path <path>] --source <filename>` | Write a file (recommended). If `--path` is omitted, write to the working directory (`<working-directory>/<filename>`); a relative `--path` is also resolved under the working directory. An absolute `--path` is used as-is (but the `/workspace/<filename>` root path is outside the OSS sync scope and is not recommended). **Binary-safe**: the content travels as raw bytes (the server's binary endpoint, with a base64 fallback for older servers) and the CLI declares its `size`/`sha256`, which the server verifies before writing (a mismatch is rejected). The response carries `server_sha256`/`sha256`/`size`/`size_verified`. |
 | `sandbox write <id> --path <absolute-path> --data "..."` | Write a small amount of inline content (`--data` has no source filename, so `--path` must be specified explicitly). |