coze-bridge 0.2.1-alpha.2 → 0.2.1-alpha.3

package/README.md

@@ -1,98 +1,218 @@
 # coze-bridge
 
-本机后台 daemon, 把云端 Agent Service 跟本地 AI agent (Claude Code / Codex / OpenClaw) 通过扩展 ACP 协议桥接起来。
+`coze-bridge` is the local bridge between the Coze cloud Agent Service and the AI
+agent runtimes on your machine, including Claude Code, Codex CLI, and OpenClaw.
 
-## 前置依赖
+This npm package is a thin wrapper. It does not contain the bridge core. On
+first run it installs and runs the native `coze-bridge` Go binary that matches
+this package version, then passes every argument through unchanged.
 
-- **Node ≥ 20**
-- 本机至少装好 `claude` / `codex` / `openclaw` 中的一个
+## Install
 
-## 用法
+Use `npx` when you want the Coze UI command to work without a separate install
+step:
 
-```bash
-# 启动 / 复用 daemon, 投递 pair (云端 UI 复制粘贴一行, 唯一保留无 verb 的入口)
+```sh
 npx -y coze-bridge@latest --pat-token=<sat_xxx> --pair-code=<xxx>
+```
 
-# 查 daemon 状态
-coze-bridge status
+Use a global npm install when you want `coze-bridge` on PATH:
 
-# 停 daemon
-coze-bridge stop
+```sh
+npm install -g coze-bridge@latest
+coze-bridge --pat-token=<sat_xxx> --pair-code=<xxx>
+```
 
-# 重新探测本地 agent 路径 / 版本
-coze-bridge refresh
+Use the native installers when Node/npm is not available:
 
-# 清理: 停 daemon + 卸自启 + 删 ~/.coze/bridge (保留 ~/.coze/agents 工作区)
-coze-bridge purge
+```sh
+# macOS/Linux
+curl -fsSL https://coze-bridge.tos-cn-beijing.volces.com/install/coze_bridge_install.sh | sh
 
-# 装 / 卸 OS supervisor 自启 (login 时自动拉起 daemon)
-coze-bridge service install
-coze-bridge service uninstall
+# Windows PowerShell
+irm https://coze-bridge.tos-cn-beijing.volces.com/install/coze_bridge_install.ps1 | iex
 ```
 
-> 老 flag (`--status` / `--stop` / `--refresh` / `--install-service` / `--uninstall`) 仍能用, 但 stderr 会打 deprecation warn, 后续 major bump 会删。建议切到新子命令形态。
->
-> 注意 `--uninstall` 在 0.1.67 起映射到新 `purge`: 删除范围从 `~/.coze` 收窄到 `~/.coze/bridge`, 不再误删 `~/.coze/agents/<id>/workspace` 里用户写过的 CLAUDE.md / SOUL.md。完全重置仍可手动 `rm -rf ~/.coze`。
+Install a specific native version or channel with the native installers:
 
-> **保活能力按平台不同**:
-> - **macOS / Linux**: 配对成功即由 launchd / systemd 接管 daemon —— 开机自启 + **进程崩溃/被杀也会自动拉起**(KeepAlive / `Restart=always`)。
-> - **Windows**: Task Scheduler 仅 **登录时自启**(ONLOGON), **不含崩溃自动重启**(daemon 崩了需重新登录或重新跑一次配对命令恢复)。崩溃自启是已知待办(需 PowerShell 改 Task XML 加 `RestartOnFailure`)。
+```sh
+curl -fsSL https://coze-bridge.tos-cn-beijing.volces.com/install/coze_bridge_install.sh \
+  | env COZE_BRIDGE_VERSION=v0.3.0 sh
 
-### 配对参数
+curl -fsSL https://coze-bridge.tos-cn-beijing.volces.com/install/coze_bridge_install.sh \
+  | env COZE_BRIDGE_CHANNEL=alpha sh
+```
 
-| Flag | 说明 |
-|---|---|
-| `--pat-token <sat_xxx>` | coze PAT token, 从 coze 平台拿 |
-| `--pair-code <xxx>` | 配对码, 从云端 UI 拿 |
+`COZE_BRIDGE_VERSION` accepts `0.3.0` or `v0.3.0` and takes precedence over
+`COZE_BRIDGE_CHANNEL`. Supported channels are `stable`, `alpha`, `beta`, `rc`,
+and `next`.
 
-支持 `--name VALUE` 与 `--name=VALUE` 两种写法。
+## Managed Layout
 
-### 自动 connect 某个 agent(可选)
+Managed installs created by `npx`, global npm, curl, or PowerShell use one
+native runtime layout:
 
-| Flag | 说明 |
-|---|---|
-| `--agent-id <id>` | pair 成功后自动 connect 该 agent: 本地已有走 reconnect/revive, 没有 (需云端协议升级) 拉详情新建 |
+```text
+~/.coze/bridge/
+  bin/coze-bridge
+  releases/<version>/coze-bridge
+  install-state.json
+  pat-token
+  bridge.token
+  logs/install-update.log
 
-```bash
-npx -y coze-bridge --pat-token=sat_xxx --pair-code=xxx --agent-id=<your-agent-id>
+~/.local/bin/coze-bridge -> ~/.coze/bridge/bin/coze-bridge
 ```
 
-### 环境路由(可选, 联调时用)
+On Windows the stable launcher is
+`%USERPROFILE%\.coze\bridge\bin\coze-bridge.cmd`, and the installer adds
+`%USERPROFILE%\.coze\bridge\bin` to the User PATH.
 
-| Flag | 说明 |
-|---|---|
-| `--env <value>` | `ppe_*` 走 `x-use-ppe: 1` + `x-tt-env`; `boe_*` 仅 `x-tt-env` |
-| `--handshake-url <url>` | 覆盖 HTTP base, 默认 `https://www.coze.cn` |
-| `--frontier-url <url>` | 覆盖 Frontier WS URL, 默认 `wss://frontier.coze.cn` |
+The stable launcher forwards to the versioned binary in `releases/<version>/`.
+Its target is the `nativeBin` recorded in `install-state.json` at install or
+update time, written into the launcher script itself; the installer and updater
+rewrite this one file on every version switch and rollback. PATH entries should
+point to the stable launcher, not directly to a versioned binary.
 
-```bash
-npx -y coze-bridge --pat-token=sat_xxx --pair-code=xxx --env=ppe_xxx
-```
+## What The Wrapper Does
 
-## 行为说明
+1. Detects the current OS/arch.
+2. Reuses an existing managed native binary when it already satisfies this npm
+   package version, or when the native updater has moved the same channel to a
+   newer version. It never downgrades a managed binary.
+3. Otherwise reads the version manifest for this npm package version, downloads
+   and verifies the platform artifact with size and sha256 checks, installs it
+   under `~/.coze/bridge/releases/<version>/`, and writes the stable launcher,
+   PATH entry, and `install-state.json`.
+4. Executes the native binary with the original arguments.
 
-- **daemon 启动自动复活 agents**: `~/.coze/agents/` 里所有未被云端主动 disconnect 的 agent, daemon 启动后会自动 spawn 子进程 + 加入路由, 不需要你一个个 reconnect
-- **device 级 10s 批量心跳**: pair 成功后每 10s 上行 1 帧 `_agent/health`, 装该 device 下所有 eligible agent (`agents:[{agentId,status},...]`), 新 agent 上线毫秒级出首帧
-- **deviceId 不持久化**: 每次 pair 由云端 handshake 接口分配, 切环境 / 重启 daemon 都用新值
-- **cloud agent 跟本机 framework 解耦**: `_agent/create` 带 `_meta.cozeDeployType=cloud` 时 Bridge 直接 ack 不 spawn — agent 在云端跑, 本机没装对应 framework 也行
+The wrapper takes the cross-language `~/.coze/bridge/install.lock` directory lock
+around writes. It never runs the updater state machine, stops or starts the
+daemon, restores `connect`, or rolls back. Those actions live in the native Go
+runtime. If the wrapper finds a pending update, it only delegates to an
+executable native entry.
 
-## 工作目录
+## Update
 
+Run updates from a managed install:
+
+```sh
+coze-bridge update
 ```
-~/.coze/
-├── bridge/                 # daemon 文件
-│   ├── lib/index.js        # 固化的 dist (npx 首次执行复制过来)
-│   ├── bridge.pid          # PID
-│   ├── bridge.port         # IPC HTTP 端口
-│   ├── bridge.token        # IPC token (mode 0600)
-│   ├── bridge.log
-│   └── config.json         # frameworks_cache + libVersion (不存 deviceId, 每次 pair 拿)
-└── agents/<agentId>/       # 每个 agent 一个目录, daemon 重启自动复活
-    ├── config.json         # mode 0600 (含 cozeIdentity / model / modelToken / sessions / ...)
-    ├── workspace/          # 子进程 cwd, CLAUDE.md / AGENTS.md / SOUL.md 在这
-    └── logs/
+
+The native updater reads the installed channel from `install-state.json`, checks
+the channel manifest, downloads and verifies the target artifact, switches the
+stable launcher to the new version, and restores `connect` when the daemon was
+running before the update. If `~/.coze/bridge/pat-token` is missing, the binary
+update can still succeed, but you must run pair/connect again.
+
+Manual binaries that were downloaded and placed on PATH by hand are not managed
+installs. `coze-bridge update` intentionally fails for those binaries with
+`COZE_BRIDGE_UPDATE_ERROR` and points you back to npm, npx, curl, or PowerShell.
+
+## Manual Download
+
+Manual download is a fallback for running one binary directly. It does not
+create `install-state.json`, the stable launcher, or PATH entries, and it does
+not enable `coze-bridge update`.
+
+```sh
+curl -fsSLO https://coze-bridge.tos-cn-beijing.volces.com/releases/v0.3.0/manifest.json
+curl -fsSLO https://coze-bridge.tos-cn-beijing.volces.com/releases/v0.3.0/coze-bridge_v0.3.0_linux_amd64.tar.gz
+sha256sum coze-bridge_v0.3.0_linux_amd64.tar.gz
+tar -xzf coze-bridge_v0.3.0_linux_amd64.tar.gz
+./coze-bridge version
 ```
 
-## License
+Compare the sha256 with the matching artifact entry in `manifest.json` before
+running the binary. Windows artifacts are zip files containing
+`coze-bridge.exe`.
+
+## PATH Notes
+
+On macOS/Linux the installer creates `~/.local/bin/coze-bridge` as a symlink to
+the stable launcher when possible, or as a tiny launcher script when symlinks are
+not available. Add `~/.local/bin` to PATH if your shell cannot find
+`coze-bridge`.
+
+On Windows, open a new shell after the PowerShell installer changes the User
+PATH. You can always run the managed launcher directly:
+
+```powershell
+& "$env:USERPROFILE\.coze\bridge\bin\coze-bridge.cmd" version
+```
 
-MIT
+If an older global npm or TypeScript install appears earlier on PATH, install
+can still succeed but will print a shadowing warning. Update PATH ordering so
+the managed launcher is found first, or run the managed launcher by full path.
+
+## Service Install
+
+Managed installs make `service install` point launchd, systemd, or Task
+Scheduler at the stable launcher. After `coze-bridge update`, the service keeps
+the same command and the launcher forwards to the updated version.
+
+When you run `service install` from a manual binary, the service is bound to that
+exact binary path. It will not move automatically with `coze-bridge update`;
+install through npm, npx, curl, or PowerShell first if you want managed update
+behavior.
+
+## Migration From The Old TypeScript Package
+
+The old TypeScript package used the same package name and stored local state
+under `~/.coze/bridge`. The Go package keeps that state directory and preserves
+agent workspaces under `~/.coze/agents/<agentId>/workspace`.
+
+Common migration paths:
+
+- Running the Coze UI command again with `npx -y coze-bridge@latest ...` lands
+  on this wrapper, installs the native runtime, and then starts native pair or
+  connect.
+- Running `npm install -g coze-bridge@latest` replaces the old global npm entry
+  with this wrapper. The first `coze-bridge ...` command installs and runs the
+  native binary.
+- If an old TypeScript update command runs
+  `npx -y --ignore-existing coze-bridge@latest connect`, that first hop also
+  lands on this wrapper and enters the native runtime.
+
+The native runtime stops or reuses any old local daemon before starting the Go
+daemon. It reads compatible configuration fields but does not treat unknown old
+`config.json` fields as new behavior.
+
+## Environment
+
+- `COZE_BRIDGE_NATIVE_BIN`: absolute path to a native binary to run directly.
+  Invalid paths are reported and skipped.
+- `COZE_BRIDGE_DOWNLOAD_BASE`: override the release download root. The value
+  must be an HTTPS URL.
+- `COZE_BRIDGE_VERSION`: native installer-only override for an exact version.
+- `COZE_BRIDGE_CHANNEL`: native installer-only channel override when no exact
+  version is set.
+
+## Troubleshooting
+
+- `COZE_BRIDGE_INSTALL_ERROR stage=manifest`: the manifest is missing, invalid,
+  for an unsupported schema, or not consistent with the requested version or
+  channel.
+- `COZE_BRIDGE_INSTALL_ERROR stage=checksum`: the downloaded manifest or
+  artifact did not match the expected sha256 or size. The current install is
+  left untouched.
+- `COZE_BRIDGE_INSTALL_ERROR stage=lock`: another installer or updater owns
+  `~/.coze/bridge/install.lock`. Retry after that process exits.
+- `COZE_BRIDGE_UPDATE_ERROR stage=preflight`: the current binary is not a
+  managed install, or `install-state.json`/stable launcher/native binary is
+  missing or inconsistent.
+- Pending update errors are recovered by the native runtime. Re-run
+  `coze-bridge update` or `coze-bridge connect` from a managed launcher.
+
+Install and update logs are written to
+`~/.coze/bridge/logs/install-update.log`. They include stages, versions,
+manifest URLs, artifact URLs, checksums, and native binary paths. They must not
+contain PAT tokens, bridge tokens, or pair codes.
+
+## Package Boundaries
+
+- No `preinstall`, `install`, or `postinstall` lifecycle scripts: `npm install`
+  never downloads a native artifact or writes `~/.coze/bridge`.
+- The npm package ships only `bin/`, `lib/`, and this README. It does not ship
+  native artifacts or the legacy TypeScript runtime.

package/bin/coze-bridge.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+'use strict';
+
+// coze-bridge npm wrapper entry point. It installs (when needed) and execs the
+// native coze-bridge binary, passing all arguments through unchanged. The
+// wrapper never carries Go core logic and never runs the updater state machine.
+const { run } = require('../lib/main');
+
+run(process.argv.slice(2))
+  .then((code) => {
+    process.exitCode = typeof code === 'number' ? code : 0;
+  })
+  .catch((err) => {
+    process.stderr.write(`COZE_BRIDGE_INSTALL_ERROR stage=wrapper reason=${err && err.message ? err.message : err}\n`);
+    process.exitCode = 1;
+  });

package/lib/archive.js

@@ -0,0 +1,134 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+
+// extractBinary extracts the single coze-bridge[.exe] entry from an artifact
+// archive into destPath, setting an executable mode on POSIX targets.
+function extractBinary(archivePath, format, destPath, osName) {
+  const data = fs.readFileSync(archivePath);
+  let bin;
+  if (format === 'tar.gz') {
+    bin = extractFromTarGz(data, osName);
+  } else if (format === 'zip') {
+    bin = extractFromZip(data, osName);
+  } else {
+    throw new Error(`unsupported archive format ${format}`);
+  }
+  if (!bin) {
+    throw new Error('archive did not contain a coze-bridge binary');
+  }
+  fs.mkdirSync(path.dirname(destPath), { recursive: true });
+  const mode = osName === 'windows' ? 0o644 : 0o755;
+  fs.writeFileSync(destPath, bin, { mode });
+  if (osName !== 'windows') {
+    fs.chmodSync(destPath, 0o755);
+  }
+}
+
+function wantName(osName) {
+  return osName === 'windows' ? 'coze-bridge.exe' : 'coze-bridge';
+}
+
+function extractFromTarGz(gzData, osName) {
+  const tarData = zlib.gunzipSync(gzData);
+  const want = wantName(osName);
+  let offset = 0;
+  while (offset + 512 <= tarData.length) {
+    const header = tarData.subarray(offset, offset + 512);
+    if (isZeroBlock(header)) {
+      break;
+    }
+    const name = readTarString(header, 0, 100);
+    const sizeStr = readTarString(header, 124, 12).trim();
+    const size = parseInt(sizeStr, 8) || 0;
+    const typeFlag = String.fromCharCode(header[156]);
+    offset += 512;
+    const fileData = tarData.subarray(offset, offset + size);
+    offset += Math.ceil(size / 512) * 512;
+    if ((typeFlag === '0' || typeFlag === '\0') && path.basename(name) === want) {
+      return Buffer.from(fileData);
+    }
+  }
+  return null;
+}
+
+function isZeroBlock(buf) {
+  for (let i = 0; i < buf.length; i++) {
+    if (buf[i] !== 0) return false;
+  }
+  return true;
+}
+
+function readTarString(buf, start, len) {
+  const slice = buf.subarray(start, start + len);
+  let end = slice.indexOf(0);
+  if (end < 0) end = slice.length;
+  return slice.subarray(0, end).toString('utf8');
+}
+
+// extractFromZip reads the End Of Central Directory record, then walks central
+// directory entries to find and inflate the wanted binary.
+function extractFromZip(data, osName) {
+  const want = wantName(osName);
+  const eocd = findEOCD(data);
+  if (eocd < 0) {
+    throw new Error('zip end-of-central-directory not found');
+  }
+  const cdEntries = data.readUInt16LE(eocd + 10);
+  let cdOffset = data.readUInt32LE(eocd + 16);
+  for (let i = 0; i < cdEntries; i++) {
+    if (data.readUInt32LE(cdOffset) !== 0x02014b50) {
+      throw new Error('bad zip central directory signature');
+    }
+    const method = data.readUInt16LE(cdOffset + 10);
+    const compSize = data.readUInt32LE(cdOffset + 20);
+    const nameLen = data.readUInt16LE(cdOffset + 28);
+    const extraLen = data.readUInt16LE(cdOffset + 30);
+    const commentLen = data.readUInt16LE(cdOffset + 32);
+    const localOffset = data.readUInt32LE(cdOffset + 42);
+    const name = data.subarray(cdOffset + 46, cdOffset + 46 + nameLen).toString('utf8');
+    cdOffset += 46 + nameLen + extraLen + commentLen;
+    if (path.basename(name) !== want) {
+      continue;
+    }
+    return inflateLocalEntry(data, localOffset, method, compSize);
+  }
+  return null;
+}
+
+function inflateLocalEntry(data, localOffset, method, compSize) {
+  if (data.readUInt32LE(localOffset) !== 0x04034b50) {
+    throw new Error('bad zip local header signature');
+  }
+  const nameLen = data.readUInt16LE(localOffset + 26);
+  const extraLen = data.readUInt16LE(localOffset + 28);
+  const dataStart = localOffset + 30 + nameLen + extraLen;
+  const raw = data.subarray(dataStart, dataStart + compSize);
+  if (method === 0) {
+    return Buffer.from(raw);
+  }
+  if (method === 8) {
+    return zlib.inflateRawSync(raw);
+  }
+  throw new Error(`unsupported zip compression method ${method}`);
+}
+
+function findEOCD(data) {
+  const minLen = 22;
+  if (data.length < minLen) return -1;
+  const maxBack = Math.min(data.length, minLen + 0xffff);
+  for (let i = data.length - minLen; i >= data.length - maxBack; i--) {
+    if (data.readUInt32LE(i) === 0x06054b50) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+module.exports = {
+  extractBinary,
+  extractFromTarGz,
+  extractFromZip,
+};

package/lib/download.js

@@ -0,0 +1,172 @@
+'use strict';
+
+const https = require('https');
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+// buildVersionManifestURL returns <base>/releases/<version>/manifest.json.
+function buildVersionManifestURL(downloadBase, version) {
+  return joinHTTPS(downloadBase, ['releases', version, 'manifest.json']);
+}
+
+// buildChannelManifestURL returns <base>/channels/<channel>/manifest.json.
+function buildChannelManifestURL(downloadBase, channel) {
+  return joinHTTPS(downloadBase, ['channels', channel, 'manifest.json']);
+}
+
+function joinHTTPS(base, elems) {
+  const parsed = new URL(String(base == null ? '' : base));
+  if (parsed.protocol !== 'https:') {
+    throw new Error(`download base must use https, got ${JSON.stringify(parsed.protocol.replace(':', ''))}`);
+  }
+  if (!parsed.host) {
+    throw new Error('download base host is required');
+  }
+  const parts = [];
+  const basePath = parsed.pathname.replace(/^\/+|\/+$/g, '');
+  if (basePath) parts.push(basePath);
+  for (const e of elems) parts.push(String(e).replace(/^\/+|\/+$/g, ''));
+  parsed.pathname = `/${parts.join('/')}`;
+  parsed.search = '';
+  parsed.hash = '';
+  return parsed.toString();
+}
+
+// defaultHTTPGet streams an https GET, following redirects to https only.
+function defaultHTTPGet(url, onResponse, depth) {
+  const hops = depth || 0;
+  if (hops > 5) {
+    onResponse(new Error('too many redirects'));
+    return;
+  }
+  const req = https.get(url, (res) => {
+    const status = res.statusCode || 0;
+    if (status >= 300 && status < 400 && res.headers.location) {
+      res.resume();
+      let next;
+      try {
+        next = new URL(res.headers.location, url).toString();
+      } catch (err) {
+        onResponse(new Error(`invalid redirect location: ${res.headers.location}`));
+        return;
+      }
+      if (!next.startsWith('https:')) {
+        onResponse(new Error(`refusing non-https redirect to ${next}`));
+        return;
+      }
+      defaultHTTPGet(next, onResponse, hops + 1);
+      return;
+    }
+    if (status !== 200) {
+      res.resume();
+      onResponse(new Error(`unexpected status ${status} for ${url}`));
+      return;
+    }
+    onResponse(null, res);
+  });
+  req.on('error', (err) => onResponse(err));
+}
+
+// fetchBuffer downloads url into memory, enforcing a max byte cap.
+function fetchBuffer(url, opts) {
+  const httpGet = (opts && opts.httpGet) || defaultHTTPGet;
+  const maxBytes = (opts && opts.maxBytes) || 16 * 1024 * 1024;
+  return new Promise((resolve, reject) => {
+    httpGet(url, (err, res) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      const chunks = [];
+      let total = 0;
+      res.on('data', (chunk) => {
+        total += chunk.length;
+        if (total > maxBytes) {
+          res.destroy();
+          reject(new Error(`response from ${url} exceeds ${maxBytes} bytes`));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      res.on('end', () => resolve(Buffer.concat(chunks)));
+      res.on('error', reject);
+    });
+  });
+}
+
+// fetchJSON downloads and parses a JSON document, returning {buffer, json}.
+async function fetchJSON(url, opts) {
+  const buffer = await fetchBuffer(url, opts);
+  let json;
+  try {
+    json = JSON.parse(buffer.toString('utf8'));
+  } catch (err) {
+    throw new Error(`failed to parse JSON from ${url}: ${err.message}`);
+  }
+  return { buffer, json };
+}
+
+// sha256Hex returns the lowercase hex sha256 digest of a buffer.
+function sha256Hex(buffer) {
+  return crypto.createHash('sha256').update(buffer).digest('hex');
+}
+
+// downloadArtifact streams url to a temp file under destDir, verifying size
+// then sha256; it removes the temp file on any failure.
+function downloadArtifact(url, destDir, expected, opts) {
+  const httpGet = (opts && opts.httpGet) || defaultHTTPGet;
+  return new Promise((resolve, reject) => {
+    fs.mkdirSync(destDir, { recursive: true });
+    const tmp = path.join(destDir, `artifact.${process.pid}.${Date.now()}.tmp`);
+    httpGet(url, (err, res) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      const hash = crypto.createHash('sha256');
+      let total = 0;
+      const out = fs.createWriteStream(tmp);
+      const fail = (e) => {
+        out.destroy();
+        res.destroy();
+        try {
+          fs.rmSync(tmp, { force: true });
+        } catch (_) {
+          // best effort cleanup
+        }
+        reject(e);
+      };
+      res.on('data', (chunk) => {
+        total += chunk.length;
+        hash.update(chunk);
+      });
+      res.on('error', fail);
+      out.on('error', fail);
+      res.pipe(out);
+      out.on('finish', () => {
+        if (total !== expected.size) {
+          fail(new Error(`downloaded ${total} bytes, manifest size ${expected.size}`));
+          return;
+        }
+        const digest = hash.digest('hex');
+        if (digest !== String(expected.sha256).toLowerCase()) {
+          fail(new Error(`sha256 mismatch: got ${digest}, want ${expected.sha256}`));
+          return;
+        }
+        resolve(tmp);
+      });
+    });
+  });
+}
+
+module.exports = {
+  buildVersionManifestURL,
+  buildChannelManifestURL,
+  joinHTTPS,
+  defaultHTTPGet,
+  fetchBuffer,
+  fetchJSON,
+  sha256Hex,
+  downloadArtifact,
+};

package/lib/errors.js

@@ -0,0 +1,36 @@
+'use strict';
+
+// Stable error prefixes shared with the Go native runtime and installers.
+const INSTALL_ERROR = 'COZE_BRIDGE_INSTALL_ERROR';
+const UPDATE_ERROR = 'COZE_BRIDGE_UPDATE_ERROR';
+
+// BridgeError carries a failure stage so callers can print a stable prefix.
+class BridgeError extends Error {
+  constructor(prefix, stage, message) {
+    super(message);
+    this.name = 'BridgeError';
+    this.prefix = prefix;
+    this.stage = stage;
+  }
+
+  // line returns the canonical single-line diagnostic for stderr and logs.
+  line() {
+    return `${this.prefix} stage=${this.stage} reason=${this.message}`;
+  }
+}
+
+function installError(stage, message) {
+  return new BridgeError(INSTALL_ERROR, stage, message);
+}
+
+function updateError(stage, message) {
+  return new BridgeError(UPDATE_ERROR, stage, message);
+}
+
+module.exports = {
+  INSTALL_ERROR,
+  UPDATE_ERROR,
+  BridgeError,
+  installError,
+  updateError,
+};