Skip to content

fix(cli): install the pinned iii engine on Windows - #1670

Merged
rohitg00 merged 6 commits into
mainfrom
fix/windows-iii-auto-install
Nov 4, 2026
Merged

rohitg00 merged 6 commits into
mainfrom
fix/windows-iii-auto-install

Conversation

@rohitg00

@rohitg00 rohitg00 commented Nov 4, 2026 •

Copy link
Copy Markdown
Owner

Bug

On native Windows, a fresh agentmemory exits 1 after about a second:

iii-engine binary not found locally.
Auto-install unavailable on win32 — iii-x86_64-pc-windows-msvc.zip isn't tar-compatible. Install manually:
Could not start iii-engine.

Found by a clean Windows Server 2022 run of main. Every new Windows user hits it on the first start.

Cause

runIiiInstaller only knew the tar.gz path (sh + curl + tar). For zip assets it printed manual steps and returned.

Fix

  • installIiiZip in src/cli/engine-install.ts:
    • downloads the pinned asset with fetch (300 s cap)
    • checks it against the same pinned III_RELEASE_SHA256 table the other platforms use; no pinned checksum means no download, a mismatch deletes the archive before extraction
    • extracts with %SystemRoot%\System32\tar.exe -xf and falls back to powershell.exe -NoProfile -NonInteractive Expand-Archive; both run through spawnSync with shell: false and windowsHide: true; PowerShell paths are single-quote literals with ' doubled
    • succeeds only when iii.exe exists in the private bin directory afterwards
  • runIiiInstaller uses it for zip assets; on failure it prints the download URL, the expected SHA-256 and the target directory.

The consent rules do not change: Windows already chose the install path without a prompt (#1658).

Testing

  • test/engine-install.test.ts (8 new): extractor order and arguments, PowerShell quoting, install on matching checksum, tar to Expand-Archive fallback, no extraction on checksum mismatch, no download without a pinned checksum, extract failure when no iii.exe appears, pinned checksums present for both Windows assets.
  • npm run build, npm run skills:check, cli-engine-startup, engine-install and cli-lifecycle-safety tests pass.
  • Native Windows check on a clean machine runs on Devin before this is called done; results are added to this PR.

Summary by CodeRabbit

  • New Features
    • The CLI can install ZIP-based releases on Windows and verify the downloaded archive before installation.
    • Installed engines are kept in the app’s private binary directory. Windows installation supports two extraction methods, while other platforms continue using their existing archive installation process.
    • Downloads can use configured system proxies.
  • Bug Fixes
    • Installation cleans up temporary files after failures.
    • If automatic installation fails, the CLI provides manual download, checksum verification, and extraction instructions for the private binary directory.

Windows verification

Clean Windows Server 2022 with no iii anywhere, #1670 + #1671 + #1672 + #1362 merged: first agentmemory with CI=1 downloaded the pinned v0.25.0 zip, iii.exe landed in %USERPROFILE%\.agentmemory\bin (reports 0.25.0), livez 200 after 9.4 s; remember 201 and smart-search returned the memory. Devin session: https://app.devin.ai/sessions/19b3aff181f8433a8c776ced7a077a59

Re-verified at 4575a17 on a clean Windows Server 2022 (https://app.devin.ai/sessions/92c438809e614eb187e609812fe7f4ab): pinned iii installed through the staging folder with no leftovers, livez 200 at 7.6 s; a 2-hour-old stale archive was removed on the next install; an unreachable HTTPS_PROXY failed in 3.2 s with the manual steps and no leftover files.

A fresh agentmemory on win32 exited with "Auto-install unavailable on
win32" because the installer only handled tar.gz assets through sh,
curl and tar. Windows assets are zip files.

The zip path now downloads the pinned asset with fetch, checks it
against the same pinned SHA-256 table as every other platform, and
extracts iii.exe into the private bin directory with System32 tar.exe,
falling back to PowerShell Expand-Archive. Both run without a shell.
A missing checksum still downloads nothing, and a mismatch deletes the
archive before any extraction.
@vercel

vercel Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
agentmemory Ready Ready Preview Nov 4, 2026 8:51am UTC

Request Review

@coderabbitai

coderabbitai Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • Resume reviews
  • Trigger review
Walkthrough

The CLI now installs Windows and ZIP engine assets into agentmemory’s private binary directory. The installer downloads and verifies the archive, extracts the binary through Windows tools, and reports installation outcomes.

Changes: Windows ZIP installation

Layer / File(s) Summary
ZIP download and temporary-file handling
src/cli/engine-install.ts, test/engine-install.test.ts
The installer creates unique archive paths, removes stale temporary files, uses curl.exe when proxy variables are configured, and otherwise downloads with fetch. Child processes run asynchronously with timeout reporting. Tests cover download selection, command execution, and temporary-file cleanup.
ZIP verification and extraction
src/cli/engine-install.ts, test/engine-install.test.ts
The installer requires a pinned checksum and verifies the downloaded archive before extraction. It tries tar.exe before PowerShell extraction, stages the binary, and moves it into place. Tests cover checksum gating, extractor fallback, binary replacement, and failure cases.
CLI installation routing
src/cli.ts
Windows and ZIP assets use the ZIP installer. On success, the CLI clears the cached version probe and returns the installed binary path. On failure, it reports installer details and manual installation instructions. Windows manual extraction instructions now use %USERPROFILE%\.agentmemory\bin\iii.exe.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant installIiiZip
  participant downloadToFile
  participant tarExe
  participant PowerShell
  CLI->>installIiiZip: Install Windows or ZIP release asset
  installIiiZip->>downloadToFile: Download ZIP archive
  installIiiZip->>installIiiZip: Verify pinned SHA-256 checksum
  installIiiZip->>tarExe: Try staged extraction
  tarExe-->>installIiiZip: Return command result
  installIiiZip->>PowerShell: Try extraction if tar.exe fails
  PowerShell-->>installIiiZip: Return command result
  installIiiZip-->>CLI: Return installation outcome
Loading

Possibly related issues

  • rohitg00/agentmemory#1654: The installer still requires a network download, so it does not meet the issue’s offline-installation objective.

Possibly related PRs

Suggested reviewers: guibeira

Merge Risk: Low · previous review c0471

Windows installation is mergeable with awareness of a narrow failed-termination race that can disrupt extraction. Waiting for extractor closure would remove that risk; a timeout test would strengthen regression protection.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat… Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly and concisely describes the main change: installing the pinned iii engine on Windows.
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 12 functions across 3 files.

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches
Generate docstrings
  • Commit to this branch
  • Create a new PR
Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

devin-ai-integration[bot]

This comment was marked as resolved.

coderabbitai[bot]

This comment was marked as resolved.

- Each install downloads to its own archive name (pid plus random
  suffix), so two starts into the same bin directory cannot delete or
  overwrite each other's download before verification.
- Archive cleanup never throws, so a failed delete after a successful
  extraction no longer turns the install into a failure.
- When HTTPS_PROXY, HTTP_PROXY or ALL_PROXY is set, the zip is fetched
  with System32 curl.exe, which honors those variables on every
  supported Node version. Without a proxy the built-in fetch is used.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
devin-ai-integration[bot]

This comment was marked as resolved.

coderabbitai[bot]

This comment was marked as resolved.

- Extraction now writes into a per-install staging directory and moves
  iii.exe over the existing binary only after the staged copy exists,
  so a failed or partial extraction never destroys a working iii.exe.
- Install commands (proxied curl download, tar.exe, Expand-Archive)
  run through an async spawn with a kill timeout instead of
  spawnSync, so the startup Ctrl+C handlers keep running during a
  stalled download.
- Archives and staging folders left by earlier failed installs are
  removed once they are older than 15 minutes.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
devin-ai-integration[bot]

This comment was marked as resolved.

coderabbitai[bot]

This comment was marked as resolved.

After a failed install the warning said to extract iii.exe into
%USERPROFILE%\.agentmemory\bin, while the Setup required box below it
still said %USERPROFILE%\.local\bin. Both folders are searched; the
setup steps now name the one the installer itself uses.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
- A running curl, tar or PowerShell child is killed when the CLI
  exits, so cancelling a start with Ctrl+C no longer leaves it
  downloading or extracting in the background.
- A filesystem error while creating the staging folder or running an
  extractor now returns an extract failure, so the spinner stops and
  the manual install steps are printed.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
coderabbitai[bot]

This comment was marked as resolved.

The error handler resolved as soon as any child error fired. When a
kill failed on a child that was still running, the installer moved on
and removed the staging folder while the extractor kept writing, and
the exit-time kill was dropped. The runner now resolves from error
only when the child never spawned; otherwise it waits for close.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
@rohitg00
rohitg00 merged commit 9b86661 into main Nov 4, 2026
15 checks passed

This branch was successfully deployed

1 active deployment
Preview — 443a944f Deployed Nov 4, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant