@the-open-engine-company/zeroshot 10.8.0 → 10.9.1

package/lib/install.js

@@ -7,7 +7,7 @@ const { URL } = require('url');
 const { installSkills } = require('./skills');
 const {
   archiveName,
-  extractExecutable,
+  extractExecutables,
   parseChecksumManifest,
   targetForHost,
   verifyArchive,
@@ -25,8 +25,40 @@ const HOST_TARGETS = Object.freeze(
 );
 
 function selectTarget(platform = process.platform, arch = process.arch) {
-  const { target, executable } = targetForHost(TARGETS, platform, arch);
-  return { target, executable };
+  const { target, executable, resticExecutable } = targetForHost(TARGETS, platform, arch);
+  return { target, executable, resticExecutable };
+}
+
+function installExecutables(nativeDirectory, entries) {
+  fs.mkdirSync(nativeDirectory, { recursive: true });
+  const stage = fs.mkdtempSync(path.join(nativeDirectory, '.install-'));
+  const replaced = [];
+  const backups = [];
+  try {
+    for (const [name, contents] of entries) {
+      fs.writeFileSync(path.join(stage, name), contents, { mode: 0o755, flag: 'wx' });
+    }
+    for (const [name] of entries) {
+      const destination = path.join(nativeDirectory, name);
+      if (fs.existsSync(destination)) {
+        const backup = path.join(stage, `${name}.previous`);
+        fs.renameSync(destination, backup);
+        backups.push([destination, backup]);
+      }
+    }
+    for (const [name] of entries) {
+      const destination = path.join(nativeDirectory, name);
+      fs.renameSync(path.join(stage, name), destination);
+      replaced.push(destination);
+      if (process.platform !== 'win32') fs.chmodSync(destination, 0o755);
+    }
+  } catch (error) {
+    for (const destination of replaced.reverse()) fs.rmSync(destination, { force: true });
+    for (const [destination, backup] of backups.reverse()) fs.renameSync(backup, destination);
+    throw error;
+  } finally {
+    fs.rmSync(stage, { recursive: true, force: true });
+  }
 }
 
 function download(url, maximumBytes, redirects = 0) {
@@ -108,19 +140,11 @@ async function install(options = {}) {
   const manifest = await fetchBuffer(`${baseUrl}/SHA256SUMS`, MAX_MANIFEST_BYTES);
   const archive = await fetchBuffer(`${baseUrl}/${filename}`, MAX_ARCHIVE_BYTES);
   verifyArchive(filename, archive, manifest.toString('utf8'));
-  const executable = extractExecutable(archive, selected.executable);
+  const executables = extractExecutables(archive, [selected.executable, selected.resticExecutable]);
 
   const nativeDirectory = path.join(packageRoot, 'bin', 'native');
   const destination = path.join(nativeDirectory, selected.executable);
-  const temporary = `${destination}.${process.pid}.tmp`;
-  fs.mkdirSync(nativeDirectory, { recursive: true });
-  try {
-    fs.writeFileSync(temporary, executable, { mode: 0o755, flag: 'wx' });
-    fs.renameSync(temporary, destination);
-    if (process.platform !== 'win32') fs.chmodSync(destination, 0o755);
-  } finally {
-    fs.rmSync(temporary, { force: true });
-  }
+  installExecutables(nativeDirectory, executables);
   const skillResults = installSkills({
     packageRoot,
     homeDirectory: options.homeDirectory,
@@ -136,7 +160,7 @@ module.exports = {
   RELEASE_BASE_URL,
   RELEASE_TAG_PREFIX,
   archiveName,
-  extractExecutable,
+  extractExecutables,
   install,
   parseChecksumManifest,
   selectTarget,

package/lib/release-artifacts.js

@@ -58,43 +58,68 @@ function parseTarSize(header) {
   return Number.parseInt(value, 8);
 }
 
-function extractExecutable(archive, expectedName) {
-  let tar;
+function decompressArchive(archive) {
   try {
-    tar = zlib.gunzipSync(archive);
+    return zlib.gunzipSync(archive);
   } catch (error) {
     throw new Error(`ARCHIVE_INVALID: cannot decompress release archive: ${error.message}`);
   }
+}
+
+function readTarEntry(tar, offset, expected, executables) {
+  const header = tar.subarray(offset, offset + 512);
+  if (header.every((byte) => byte === 0)) {
+    if (!tar.subarray(offset).every((byte) => byte === 0)) {
+      throw new Error('ARCHIVE_INVALID: unexpected data after tar terminator');
+    }
+    return null;
+  }
+  const name = header.subarray(0, 100).toString('utf8').replace(/\0.*$/, '');
+  const size = parseTarSize(header.subarray(124, 136));
+  const start = offset + 512;
+  const end = start + size;
+  if (end > tar.length) throw new Error('ARCHIVE_INVALID: truncated tar entry');
+  if (!expected.has(name) || ![0, '0'.charCodeAt(0)].includes(header[156])) {
+    throw new Error(`ARCHIVE_INVALID: unexpected archive entry ${name}`);
+  }
+  if (executables.has(name)) throw new Error(`ARCHIVE_INVALID: duplicate ${name}`);
+  executables.set(name, Buffer.from(tar.subarray(start, end)));
+  return start + Math.ceil(size / 512) * 512;
+}
+
+function requireExpectedExecutables(expected, executables) {
+  for (const name of expected) {
+    if (!executables.has(name)) {
+      throw new Error(`ARCHIVE_INVALID: archive does not contain ${name}`);
+    }
+  }
+}
+
+function extractExecutables(archive, expectedNames) {
+  const expected = new Set(expectedNames);
+  if (expected.size !== expectedNames.length || expected.size === 0) {
+    throw new Error('ARCHIVE_INVALID: expected executable names must be unique');
+  }
+  const tar = decompressArchive(archive);
   let offset = 0;
-  let executable = null;
+  let terminated = false;
+  const executables = new Map();
   while (offset + 512 <= tar.length) {
-    const header = tar.subarray(offset, offset + 512);
-    if (header.every((byte) => byte === 0)) {
-      if (!tar.subarray(offset).every((byte) => byte === 0)) {
-        throw new Error('ARCHIVE_INVALID: unexpected data after tar terminator');
-      }
+    const next = readTarEntry(tar, offset, expected, executables);
+    if (next === null) {
+      terminated = true;
       break;
     }
-    const name = header.subarray(0, 100).toString('utf8').replace(/\0.*$/, '');
-    const size = parseTarSize(header.subarray(124, 136));
-    const start = offset + 512;
-    const end = start + size;
-    if (end > tar.length) throw new Error('ARCHIVE_INVALID: truncated tar entry');
-    if (name === expectedName) {
-      if (executable) throw new Error(`ARCHIVE_INVALID: duplicate ${expectedName}`);
-      executable = Buffer.from(tar.subarray(start, end));
-    } else {
-      throw new Error(`ARCHIVE_INVALID: unexpected archive entry ${name}`);
-    }
-    offset = start + Math.ceil(size / 512) * 512;
+    offset = next;
   }
-  if (!executable) throw new Error(`ARCHIVE_INVALID: archive does not contain ${expectedName}`);
-  return executable;
+  if (!terminated) throw new Error('ARCHIVE_INVALID: archive has no tar terminator');
+  requireExpectedExecutables(expected, executables);
+  return executables;
 }
 
 module.exports = {
   archiveName,
-  extractExecutable,
+  extractExecutables,
   parseChecksumManifest,
   sha256,
   targetForHost,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-open-engine-company/zeroshot",
-  "version": "10.8.0",
+  "version": "10.9.1",
   "description": "Verified prebuilt binary installer for the standalone Zeroshot engine",
   "homepage": "https://the-open-engine.github.io/zeroshot/",
   "license": "MIT",

package/skills/zeroshot/SKILL.md

@@ -52,6 +52,41 @@ zeroshot connection list --target cloud --scope org
 Do not assume a profile creates a pull request. `--pr` requests pull-request delivery and `--ship`
 requests merge delivery when materializing a compatible template; use either only when intended.
 
+## Prepare the execution environment
+
+Environments belong to a run, independently of its profile. A `local:NAME` profile can run on a
+Docker target with its own environment. For Docker or Cloud, pass
+`--environment environment.json` with a flat definition such as:
+
+```json
+{
+  "setup": "apt-get update && apt-get install -y jq",
+  "startup": "npm ci",
+  "variables": { "CI": "true" }
+}
+```
+
+Cloud resolves an omitted environment from the repository's User default, then Org default, then
+Base. `--no-environment` bypasses defaults. Choose saved environments through Cloud's UI or API;
+the CLI accepts a concrete JSON file. Local runs use the invoking machine and reject setup/startup
+and hook connections.
+
+Setup runs as root before checkout or restoration, so it cannot read repository files. Startup
+runs as the workspace user in the checkout; workers and reviewers share its dependencies and
+services. Both hooks rerun on resume, so startup must tolerate existing workspace files.
+Checkpoints restore files and graph progress, not running services or agent conversations.
+
+Put shared executables in `$ZEROSHOT_TOOLS/bin` and project dependencies in the workspace.
+Shell exports do not persist between hooks or agents; use `variables` for nonsecret values and
+`connections` for required secret field names. Hook connections and node connections are separate.
+On a direct Docker target, root setup changes the container shared by its runs.
+
+Preparation failures stop before agent execution without spending repair attempts. Inspect the
+failed phase and logs; fix the environment instead of requesting unrelated code repairs. Resume
+reuses the accepted definition, so an edited environment requires a new run. For a pinned Node
+installation and service/Docker conventions, see the
+[environment guide](https://the-open-engine.github.io/zeroshot/current/guides/runtime-environments/).
+
 ## Expose a profile over ACP
 
 Start `zeroshot acp` only when the user explicitly asks to expose a Zeroshot graph as an ACP agent.

package/targets.json

@@ -3,30 +3,35 @@
     "platform": "linux",
     "arch": "x64",
     "target": "x86_64-unknown-linux-musl",
-    "executable": "zeroshot"
+    "executable": "zeroshot",
+    "resticExecutable": "restic"
   },
   {
     "platform": "linux",
     "arch": "arm64",
     "target": "aarch64-unknown-linux-musl",
-    "executable": "zeroshot"
+    "executable": "zeroshot",
+    "resticExecutable": "restic"
   },
   {
     "platform": "darwin",
     "arch": "x64",
     "target": "x86_64-apple-darwin",
-    "executable": "zeroshot"
+    "executable": "zeroshot",
+    "resticExecutable": "restic"
   },
   {
     "platform": "darwin",
     "arch": "arm64",
     "target": "aarch64-apple-darwin",
-    "executable": "zeroshot"
+    "executable": "zeroshot",
+    "resticExecutable": "restic"
   },
   {
     "platform": "win32",
     "arch": "x64",
     "target": "x86_64-pc-windows-msvc",
-    "executable": "zeroshot.exe"
+    "executable": "zeroshot.exe",
+    "resticExecutable": "restic.exe"
   }
 ]