@shuyhere/bb-agent 0.0.8 → 0.0.10

package/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to BB-Agent will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.10] - 2026-04-07
+
+### Fixed
+
+- npm install now uses a longer timeout, retries release-binary downloads, and reports real download errors instead of incorrectly saying no matching prebuilt binary exists
+- npm install now shows progress logs during native binary download and verification so first-time installs on macOS/Linux are less confusing
+- fullscreen `/login` provider-family status now correctly shows OpenAI OAuth state after ChatGPT login instead of incorrectly showing the API key path as not authenticated
+
+### Changed
+
+- README install docs now lead with `npm install -g @shuyhere/bb-agent`, move terminal/font guidance into Troubleshooting, and clearly separate npm install from building from source for development
+
+## [0.0.9] - 2026-04-07
+
+### Added
+
+- `@folder/` expansion now sends a directory tree summary to the model instead of treating folders like text files
+- large `@file` expansions now send a structural outline first for long files instead of dumping the entire file immediately
+- non-UTF-8 and binary `@file` references now send metadata instead of a misleading UTF-8 read error
+
+### Fixed
+
+- fullscreen paste in iTerm2/SSH no longer corrupts the input area after paste
+- pasted file and image paths are normalized more reliably, including quoted paths and `file://` URLs
+- fullscreen prompt submission now expands `@file` references consistently
+- running tool timers continue updating after `TurnEnd` while tools are still executing
+- sub-second tool durations now display as `ms` instead of `0.0s`
+- startup Skills/Prompts/Extensions note now only appears at startup or explicit `/reload`
+- remote SSH clipboard copy no longer leaks Wayland/XDG clipboard helper warnings into the TUI
+
+### Changed
+
+- fullscreen `Ctrl+V` now falls back to clipboard text when no clipboard image is available
+- `@` autocomplete now inserts quoted file references when paths contain spaces
+
 ## [0.0.8] - 2026-04-06
 
 ### Fixed
@@ -23,4 +58,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - latest published package includes the post-0.0.7 startup, auth, model-default, and update-notice improvements
 
+[0.0.10]: https://github.com/shuyhere/bb-agent/releases/tag/v0.0.10
+[0.0.9]: https://github.com/shuyhere/bb-agent/releases/tag/v0.0.9
 [0.0.8]: https://github.com/shuyhere/bb-agent/releases/tag/v0.0.8

package/README.md

@@ -1,10 +1,37 @@
 # BB-Agent
 
+![BB-Agent title figure](assets/title-figure.png)
+
+> BB means Bridge Baby in Death Stranding. I named this project that way because while building it, I was also enjoying Death Stranding and loved the idea of connecting everyone together.
+
 A Rust-native AI coding agent for the terminal — featuring a fullscreen TUI, multi-provider support, tool use, session persistence, branching, extensions, and skills.
 
 ## Install
 
-### From source (all platforms — macOS, Linux, Windows)
+```bash
+npm install -g @shuyhere/bb-agent
+```
+
+### 1. Install with npm
+
+npm install downloads a small wrapper package first, then fetches the matching native BB-Agent binary from the GitHub release for your platform.
+
+What to expect:
+- first install can take a bit because npm downloads and verifies the native binary
+- the installer now prints progress and retry information while downloading
+- after install, run `bb`
+
+Current GitHub release binaries are published for:
+- Linux x86_64
+- macOS x86_64
+- macOS arm64 (Apple Silicon)
+- Windows x86_64
+
+If no matching prebuilt binary is available, or the download fails, npm install will print source-build instructions instead.
+
+### 2. Build from source for development
+
+Use this if you want to develop BB-Agent itself, work on the Rust codebase, or install directly without the npm downloader.
 
 Requires [Rust](https://rustup.rs). Install Rust first if you don't have it:
 
@@ -13,7 +40,7 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 source ~/.cargo/env
 ```
 
-Then build and install BB-Agent:
+Then build and install BB-Agent from source:
 
 ```bash
 git clone https://github.com/shuyhere/bb-agent.git
@@ -23,16 +50,6 @@ cargo install --path crates/cli
 
 This compiles the `bb` binary and installs it to `~/.cargo/bin/bb` (which Rust adds to your PATH).
 
-### npm (Linux/macOS/Windows — downloads matching prebuilt binary when available)
-
-```bash
-npm install -g @shuyhere/bb-agent
-```
-
-> If no matching prebuilt binary is available for your platform, npm install will print source-build instructions instead. After install, run `bb` to start.
->
-> Current GitHub release binaries are published for Linux x86_64, macOS x86_64/arm64, and Windows x86_64.
-
 ## Getting Started
 
 ### 1. Start the TUI
@@ -170,6 +187,38 @@ BB-Agent uses layered configuration:
 | `bb-tui` | Terminal UI components and fullscreen experience |
 | `bb-cli` | The `bb` command-line application |
 
+## Troubleshooting
+
+### Terminal & Font Compatibility
+
+BB-Agent uses Unicode glyphs and ANSI color in the fullscreen TUI. For the best visual experience, use a modern terminal and a Unicode-capable monospace font such as:
+
+- JetBrains Mono
+- SF Mono / Menlo
+- Fira Code
+- Cascadia Mono
+- Nerd Font variants of the above
+
+If some symbols look broken, missing, or too narrow in your terminal:
+
+1. switch to a Unicode-capable monospace font
+2. make sure your terminal uses UTF-8
+3. enable BB-Agent compatibility mode
+
+Compatibility mode uses safer ASCII-style fallback glyphs for spinner/status/tool markers:
+
+```bash
+BB_TUI_COMPAT=1 bb
+```
+
+Or set this in `~/.bb-agent/settings.json`:
+
+```json
+{
+  "compatibility_mode": true
+}
+```
+
 ## Documentation
 
 - [Configuration Reference](docs/configuration.md) — settings.json, AGENTS.md, templates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shuyhere/bb-agent",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "BB-Agent — a Rust-native AI coding agent for the terminal",
   "license": "MIT",
   "repository": {

package/scripts/postinstall.js

@@ -7,13 +7,15 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 const https = require("https");
+const http = require("http");
 
 const packageJson = require("../package.json");
 const BINARY_RELEASE_TAG = `v${packageJson.version}`;
 const REPO = "shuyhere/bb-agent";
-const PACKAGE_ROOT = path.resolve(__dirname, "..");
 const NATIVE_DIR = path.join(__dirname, "..", "native");
-const DOWNLOAD_TIMEOUT_MS = 15_000;
+const DOWNLOAD_TIMEOUT_MS = 120_000;
+const MAX_REDIRECTS = 8;
+const MAX_DOWNLOAD_ATTEMPTS = 3;
 
 function isWindows() {
   return os.platform() === "win32";
@@ -44,34 +46,6 @@ function getTarget() {
   return `${a}-${p}`;
 }
 
-function downloadBinary(url, dest, timeoutMs) {
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => reject(new Error("Download timed out")), timeoutMs);
-
-    const follow = (url, redirects = 0) => {
-      if (redirects > 5) { clearTimeout(timer); return reject(new Error("Too many redirects")); }
-
-      const mod = url.startsWith("https") ? https : require("http");
-      const req = mod.get(url, (res) => {
-        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-          return follow(res.headers.location, redirects + 1);
-        }
-        if (res.statusCode !== 200) {
-          clearTimeout(timer);
-          return reject(new Error(`HTTP ${res.statusCode}`));
-        }
-        const file = fs.createWriteStream(dest);
-        res.pipe(file);
-        file.on("finish", () => { clearTimeout(timer); file.close(); resolve(); });
-        file.on("error", (e) => { clearTimeout(timer); reject(e); });
-      });
-      req.on("error", (e) => { clearTimeout(timer); reject(e); });
-      req.on("timeout", () => { req.destroy(); clearTimeout(timer); reject(new Error("Request timed out")); });
-    };
-    follow(url);
-  });
-}
-
 function assetNameForTarget(target) {
   return isWindows() ? `bb-${target}.exe` : `bb-${target}`;
 }
@@ -87,60 +61,232 @@ function hasBundledNativeBinary() {
   }
 }
 
-async function tryDownloadPrebuilt(target) {
-  const assetName = assetNameForTarget(target);
-  const url = `https://github.com/${REPO}/releases/download/${BINARY_RELEASE_TAG}/${assetName}`;
-
-  fs.mkdirSync(NATIVE_DIR, { recursive: true });
-  const dest = nativeBinaryPath();
+function makeDownloadError(kind, message, statusCode) {
+  const err = new Error(message);
+  err.kind = kind;
+  if (statusCode) err.statusCode = statusCode;
+  return err;
+}
 
-  try {
-    console.log(`Downloading BB-Agent ${BINARY_RELEASE_TAG} for ${target}...`);
-    await downloadBinary(url, dest, DOWNLOAD_TIMEOUT_MS);
-    fs.chmodSync(dest, 0o755);
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes <= 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB"];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value.toFixed(value >= 10 || unit === 0 ? 0 : 1)} ${units[unit]}`;
+}
 
-    // Verify the binary is executable
-    try {
-      execSync(`"${dest}" --version`, { stdio: "pipe", timeout: 5000 });
-    } catch {
-      // Binary may not run on this platform (e.g. wrong arch) — remove it
-      fs.unlinkSync(dest);
-      return false;
+function requestBinary(url, dest, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    if (redirects > MAX_REDIRECTS) {
+      reject(makeDownloadError("redirect", "Too many redirects"));
+      return;
     }
 
-    console.log("✓ BB-Agent binary installed successfully.");
-    return true;
+    const client = url.startsWith("https:") ? https : http;
+    const req = client.get(
+      url,
+      {
+        headers: {
+          "User-Agent": `${packageJson.name}/${packageJson.version} (postinstall)`,
+          Accept: "application/octet-stream,application/octet-stream; q=0.9,*/*;q=0.1",
+        },
+      },
+      (res) => {
+        const status = res.statusCode || 0;
+
+        if (status >= 300 && status < 400 && res.headers.location) {
+          res.resume();
+          requestBinary(res.headers.location, dest, redirects + 1)
+            .then(resolve)
+            .catch(reject);
+          return;
+        }
+
+        if (status === 404) {
+          res.resume();
+          reject(makeDownloadError("not-found", `HTTP 404 for ${url}`, 404));
+          return;
+        }
+
+        if (status !== 200) {
+          res.resume();
+          reject(makeDownloadError("http", `HTTP ${status} for ${url}`, status));
+          return;
+        }
+
+        const totalBytes = Number(res.headers["content-length"] || 0);
+        let downloadedBytes = 0;
+        let lastLoggedAt = Date.now();
+        if (totalBytes > 0) {
+          console.log(`Release asset size: ${formatBytes(totalBytes)}.`);
+        } else {
+          console.log("Release asset size: unknown (streaming download).");
+        }
+
+        const file = fs.createWriteStream(dest);
+        let settled = false;
+
+        const finish = (fn, value) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeout);
+          fn(value);
+        };
+
+        res.on("data", (chunk) => {
+          downloadedBytes += chunk.length;
+          const now = Date.now();
+          if (now - lastLoggedAt >= 5000) {
+            lastLoggedAt = now;
+            if (totalBytes > 0) {
+              const percent = Math.min(100, Math.round((downloadedBytes / totalBytes) * 100));
+              console.log(
+                `Download progress: ${percent}% (${formatBytes(downloadedBytes)} / ${formatBytes(totalBytes)})`
+              );
+            } else {
+              console.log(`Downloaded ${formatBytes(downloadedBytes)} so far...`);
+            }
+          }
+        });
+
+        file.on("finish", () => {
+          file.close((closeErr) => {
+            if (closeErr) {
+              finish(reject, makeDownloadError("write", closeErr.message));
+            } else {
+              if (totalBytes > 0) {
+                console.log(
+                  `Download complete: ${formatBytes(downloadedBytes)} / ${formatBytes(totalBytes)}.`
+                );
+              } else {
+                console.log(`Download complete: ${formatBytes(downloadedBytes)}.`);
+              }
+              finish(resolve);
+            }
+          });
+        });
+
+        file.on("error", (err) => {
+          try { file.close(() => {}); } catch {}
+          try { fs.unlinkSync(dest); } catch {}
+          finish(reject, makeDownloadError("write", err.message));
+        });
+
+        res.on("error", (err) => {
+          try { file.close(() => {}); } catch {}
+          try { fs.unlinkSync(dest); } catch {}
+          finish(reject, makeDownloadError("network", err.message));
+        });
+
+        res.pipe(file);
+      }
+    );
+
+    const timeout = setTimeout(() => {
+      req.destroy(makeDownloadError("timeout", `Download timed out after ${DOWNLOAD_TIMEOUT_MS}ms`));
+    }, DOWNLOAD_TIMEOUT_MS);
+
+    req.on("error", (err) => {
+      clearTimeout(timeout);
+      reject(makeDownloadError(err.kind || "network", err.message));
+    });
+  });
+}
+
+function verifyBinary(dest) {
+  try {
+    execSync(`"${dest}" --version`, { stdio: "pipe", timeout: 5000 });
+    return { ok: true };
   } catch (err) {
-    // Clean up partial download
-    try { fs.unlinkSync(dest); } catch {}
-    return false;
+    return {
+      ok: false,
+      message: err && err.message ? err.message : "binary verification failed",
+    };
   }
 }
 
+async function tryDownloadPrebuilt(target) {
+  const assetName = assetNameForTarget(target);
+  const url = `https://github.com/${REPO}/releases/download/${BINARY_RELEASE_TAG}/${assetName}`;
 
-async function main() {
-  if (process.env.BB_SKIP_POSTINSTALL) {
-    return;
-  }
+  fs.mkdirSync(NATIVE_DIR, { recursive: true });
+  const dest = nativeBinaryPath();
 
-  if (hasBundledNativeBinary()) return;
+  let lastError = null;
+  for (let attempt = 1; attempt <= MAX_DOWNLOAD_ATTEMPTS; attempt += 1) {
+    try {
+      console.log(
+        `Downloading BB-Agent ${BINARY_RELEASE_TAG} for ${target} (attempt ${attempt}/${MAX_DOWNLOAD_ATTEMPTS})...`
+      );
+      console.log("This may take a little while on first install because npm downloads and verifies the native binary from the GitHub release.");
+      try { fs.unlinkSync(dest); } catch {}
+      await requestBinary(url, dest, 0);
+      fs.chmodSync(dest, 0o755);
 
-  const target = getTarget();
+      const verified = verifyBinary(dest);
+      if (!verified.ok) {
+        try { fs.unlinkSync(dest); } catch {}
+        return {
+          ok: false,
+          kind: "verify",
+          message: `Downloaded binary could not run: ${verified.message}`,
+        };
+      }
 
-  // Try prebuilt binary
-  if (target) {
-    const ok = await tryDownloadPrebuilt(target);
-    if (ok) return;
+      console.log("Verifying downloaded binary...");
+      console.log("✓ BB-Agent binary installed successfully.");
+      return { ok: true };
+    } catch (err) {
+      lastError = err;
+      try { fs.unlinkSync(dest); } catch {}
+      if (err.kind === "not-found") {
+        return {
+          ok: false,
+          kind: "not-found",
+          message: `No release asset named ${assetName} was found for ${BINARY_RELEASE_TAG}.`,
+        };
+      }
+      if (attempt < MAX_DOWNLOAD_ATTEMPTS) {
+        await new Promise((resolve) => setTimeout(resolve, 1000 * attempt));
+      }
+    }
   }
 
-  // No prebuilt available — print instructions instead of trying cargo build
-  // (cargo build takes 5+ minutes and would appear to hang)
-  const platform = `${os.platform()}-${os.arch()}`;
+  return {
+    ok: false,
+    kind: (lastError && lastError.kind) || "download",
+    message: (lastError && lastError.message) || "unknown download failure",
+  };
+}
+
+function printFallbackHelp(platform, reason) {
   console.log("");
-  console.log(`BB-Agent ${packageJson.version}: matching prebuilt binary not available yet for ${platform}.`);
+  if (reason && reason.kind === "not-found") {
+    console.log(
+      `BB-Agent ${packageJson.version}: matching prebuilt binary is not published for ${platform}.`
+    );
+  } else if (reason) {
+    console.log(
+      `BB-Agent ${packageJson.version}: failed to download the prebuilt binary for ${platform}.`
+    );
+    console.log(`Reason: ${reason.message}`);
+  } else {
+    console.log(
+      `BB-Agent ${packageJson.version}: matching prebuilt binary not available yet for ${platform}.`
+    );
+  }
   console.log("");
   console.log("╔══════════════════════════════════════════════════════════════╗");
-  console.log("║  BB-Agent: no prebuilt binary for " + platform.padEnd(19) + "       ║");
+  console.log(
+    "║  BB-Agent: npm could not install native binary for " +
+      platform.padEnd(16) +
+      "   ║"
+  );
   console.log("║                                                              ║");
   console.log("║  Install Rust (if needed):                                   ║");
   console.log("║    https://rustup.rs                                         ║");
@@ -155,8 +301,40 @@ async function main() {
   console.log("");
 }
 
-main().catch((err) => {
-  // Never fail npm install — just print instructions
-  console.error("BB-Agent postinstall notice:", err.message);
-  console.log("Install manually: git clone https://github.com/shuyhere/bb-agent.git && cd bb-agent && cargo install --path crates/cli");
-});
+async function main() {
+  if (process.env.BB_SKIP_POSTINSTALL) {
+    return;
+  }
+
+  if (hasBundledNativeBinary()) {
+    return;
+  }
+
+  const target = getTarget();
+  const platform = `${os.platform()}-${os.arch()}`;
+
+  if (target) {
+    const result = await tryDownloadPrebuilt(target);
+    if (result.ok) {
+      return;
+    }
+    printFallbackHelp(platform, result);
+    return;
+  }
+
+  printFallbackHelp(platform, {
+    kind: "unsupported-platform",
+    message: `Unsupported target mapping for ${platform}`,
+  });
+}
+
+main()
+  .catch((err) => {
+    console.error("BB-Agent postinstall notice:", err && err.message ? err.message : String(err));
+    console.log(
+      "Install manually: git clone https://github.com/shuyhere/bb-agent.git && cd bb-agent && cargo install --path crates/cli"
+    );
+  })
+  .finally(() => {
+    process.exitCode = 0;
+  });