Skip to content

Agent: carry the python tool's CPython inside the Windows executable - #1537

Merged
AnthonyRonning merged 4 commits into
masterfrom
claude/windows-python-runtime
Nov 10, 2026
Merged

AnthonyRonning merged 4 commits into
masterfrom
claude/windows-python-runtime

Conversation

@AnthonyRonning

@AnthonyRonning AnthonyRonning commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Windows packages now carry the CPython runtime the python tool runs, so the tool can be switched on there as on macOS (PR #1412) and Linux (PR #1414).

Why it is inside the executable

The spec's recommended option was a runtime/python subtree in each Windows generation. That cannot reach existing installations:

  • A generation is exactly four files. The root maple-agent.exe launcher that NSIS installed checks every generation against that list at startup (scan_generation), and in-app updates never replace it. Every existing installation would refuse a generation with a runtime in it until the user ran a new installer by hand.
  • Installed updaters check the same list in the archive, so they would refuse the download too.

Inside maple-agent.exe the runtime needs no updater or launcher change, arrives with installs and in-app updates alike, needs no network on first use, and is covered by the executable's Authenticode signature.

What changed

  • Build (scripts/build-release.sh): on Windows it prepares the hash-pinned runtime for the target, packs it with the new prepare-python.py --archive (sorted, no timestamps, so the same runtime gives the same bytes) and sets MAPLE_CODE_MODE_EMBEDDED_RUNTIME. maple-code-mode's new build script compiles that archive in. Without the variable nothing is embedded, so development builds are unchanged.
  • Packaging (scripts/windows-release.py): refuses an executable with no embedded runtime.
  • First use (EmbeddedPython, PythonWorkers): the first python call unpacks the archive into %LOCALAPPDATA%\<data namespace>\python-runtime\<digest>\.
    • The folder is created with the store's private ACL, beside store-v1 and outside its backups.
    • Later calls and restarts reuse the copy. A receipt is written last and lists every file with its size, so an interrupted copy, or one with a missing or cut-short file, is unpacked again. File contents are not re-read on reuse.
    • A new copy's interpreter is started once before the worker uses it, so the slow first start of never-run files does not count against the worker's 10 s startup deadline.
    • An update with a different runtime replaces the old copy.
    • Settings → Tools lists Python without unpacking anything.
  • Uninstall: the NSIS uninstaller removes python-runtime. It is a copy of installed files; user data stays. The root uninstall.exe, like the launcher, is never replaced by in-app updates, so an installation that only updates in-app keeps its old uninstaller and leaves this folder (56 MB) behind until an installer is run again.
  • maple-agent python-check (hidden): starts the bundled Python the way a task's first call does and runs one cell that imports the native modules and pip. It needs no account, so packaging checks and the QA VM can use it.
  • CI: the Windows packaging lanes now also select on the runtime pin and preparation script. The Windows setup action selects a Python 3.13 or later from the runner's tool cache: prepare-python.py requires it and the x64 images default to an older one, which also stopped agent-full-windows on master.

Cost

  • maple-agent.exe grows by about 18.5 MB (x64), in the installer and the updater archive.
  • The unpacked runtime is 56 MB in 1,985 files.
  • The first python call on a machine waits for the unpacking.

Not in this PR

  • The unpacked python.exe and DLLs are Python Build Standalone's files, without Maple's signature. Signing them would have to happen before the executable is built, and the build job has no signing credentials by design.
  • No new dependency versions: tar, flate2 and sha2 were already in Cargo.lock.

Validation

  • just ci passes on macOS, with new tests for packing, unpacking, reuse, repair, replacement, unsafe archive paths and the private folder.
  • A local build with the Windows x64 archive embedded carries the marker packaging looks for.
  • python-check passes on macOS against the runtime beside the executable.
  • CI is green with ci:package and ci:windows, including the new native Windows test that unpacks the staged runtime and runs a cell from the copy.
  • The x64 package from this PR's ci:package run (build 685), on the windows-11 QA VM (x64 under emulation, about 20 times slower than hardware, Defender off), installed and run as the desktop user at normal integrity:
    • Silent install over an existing Dev installation and onto a clean root: success.
    • maple-agent python-check on a machine with no copy: unpacks 1,985 files into %LOCALAPPDATA%\maple-agent-dev\python-runtime\<digest> and runs the cell (CPython 3.14.7, native modules and pip import). The folder's ACL grants only the user.
    • A second run reuses the copy. After deleting python314.dll the copy is unpacked again and the cell runs. An earlier build reused the damaged copy; the receipt change fixes that.
    • Uninstall removes the installation and python-runtime; install and uninstall twice in a row both clean.
  • Startup deadline: on this VM a warm worker start takes about 5 s of the 10 s deadline. Before the warm-up change the first call after unpacking missed the deadline in the one run made; with it the first call passed in 6 of 7 runs. The deadline is unchanged.
  • The ARM64 package from the same run (build 685), on the windows-11-arm64 QA VM (native speed, Defender real-time protection on):
    • Silent install as the desktop user: success in 15 s.
    • python-check: first run unpacks and runs in 7 to 9 s, a second run reuses the copy in 2 to 3 s, and a copy with python314.dll deleted is unpacked again. Defender recorded no detection.
    • In the app, signed in with the Dev QA account: Python is listed in Settings → Tools, off. Switched on, with no copy on disk, a task made two python calls. The first unpacked the runtime and printed CPython 3.14.7 on ARM64; the second read the first call's variable.
  • Not run: the tool in the app's window on x64, real hardware, and third-party antivirus.

🤖 Generated with Claude Code

A Windows generation holds exactly four files. The root launcher of every
existing installation is never replaced by an in-app update and refuses a
generation with anything else, and installed updaters refuse an archive
with extra entries. So the runtime cannot sit beside the executable as it
does on macOS and Linux without stranding those installations.

build-release.sh now prepares the hash-pinned runtime on Windows, packs it
(prepare-python.py --archive) and compiles the archive into
maple-agent.exe, where the Authenticode signature covers it. Packaging
refuses an executable without one. The first python call unpacks it into
%LOCALAPPDATA%\<data namespace>\python-runtime\<digest>, a private folder
beside store-v1, and later calls reuse it. An interrupted or damaged copy
is unpacked again, a new runtime replaces the old copy, and the
uninstaller removes the folder.

`maple-agent python-check` (hidden) starts the bundled Python the same way
and runs one cell, for packaging checks that have no account.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@AnthonyRonning AnthonyRonning added ci:windows Run Windows checks on this PR ci:package Build unsigned packages on this PR labels Nov 10, 2026
AnthonyRonning and others added 3 commits November 9, 2026 21:05
prepare-python.py requires build Python 3.13. The x64 Windows images default
to an older python3, so agent-package-windows and agent-full-windows stopped
at that check; the tool cache holds a newer one.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
On the Windows QA VM the first python call after unpacking missed the worker's
10 s startup deadline: the first start of files Windows has never run is slow.
The second call passed. Unpacking now runs the interpreter once, importing what
the worker imports, so that one-time cost is not counted against the deadline.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The reuse check looked only at the receipt, manifest, interpreter and worker.
On the QA VM a copy without python314.dll was reused and could not start. The
receipt now lists every file with its size and reuse checks each one.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@AnthonyRonning
AnthonyRonning marked this pull request as ready for review November 10, 2026 19:37
@AnthonyRonning
AnthonyRonning merged commit d0dfee5 into master Nov 10, 2026
40 checks passed
@AnthonyRonning
AnthonyRonning deleted the claude/windows-python-runtime branch November 10, 2026 19:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci:package Build unsigned packages on this PR ci:windows Run Windows checks on this PR

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant