Skip to content

fix(computers): a composed computer's key doesn't change with the id its driver is stored under - #738

Merged
earakely-scale merged 1 commit into
mainfrom
edgararakelyan/driver-folder-by-declared-name
Nov 18, 2026
Merged

earakely-scale merged 1 commit into
mainfrom
edgararakelyan/driver-folder-by-declared-name

Conversation

@earakely-scale

@earakely-scale earakely-scale commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

What

A composed computer's key no longer depends on the id its driver is stored under. So the same computer registered
under two prefixes shares its composes instead of composing everything again.

The composer installed the driver in /opt/agentenv/drivers/<name>, and named its programs and their file after it,
with <name> the last / part of the driver's id. Two cases:

  • For a shipped driver, @local/agentenv-framework/drivers/reference, that's reference.
  • For a driver a bundle registered with a prefix, psi-tc-shelfway-cracked-lamp-refund-full-desktop-reference, the
    id has no /. The whole prefixed id named the folder, went into the composed Dockerfile, and changed the key.

The folder is now named for the name the driver's class declares, @computer_driver(name=...), read at put into its
declaration.name (gate.driver_folder). That's the same way an app's folder is named for its environment name
(gate.app_folder). It's used for the container form, the Windows and Omarchy disks, and the macOS VM bundle.

No key changes for the shipped drivers. Every one declares the name of its folder:

  • reference, cua-driver and page;
  • agent-desktop, macos-harness, codex-computer-use and aside.

So a computer composed of one keeps its key. A driver stored under any other id gets its declared name once, and a
computer composed of it composes once more.

Why

A PSI sweep in synthetic-pipelines registers each task's whole-computer desktop under the task's own prefix,
psi-tc-<spec>-full-desktop-. Each registration composed the desktop and every app's one-app computer again, about
30 min and 80 GB each. Two of fifteen registrations filled a 242 GB builder.

Two specs' staged bundles were byte-identical, yet their keys differed. Their composed images differed in one thing,
the driver's folder:

  • /opt/agentenv/drivers/psi-tc-shelfway-cracked-lamp-refund-full-desktop-reference in one;
  • /opt/agentenv/drivers/psi-tc-curbfinch-furnish-day-full-desktop-reference in the other.

The same would happen to any computer registered more than once under different prefixes, on a hub as well.

Proof

  • A new unit test puts the same driver under a second id whose last part differs. The computer composed of it
    reuses the first one's images, with the same keys.
    • Without the change it fails: 4 builds instead of 2, no reuse.
  • The computer, bundle and driver unit tests: 2,523 passed, 11 skipped.
    • One fails, test_disk_recipe.py::test_a_windows_install_boots_its_iso_first_pressing_enter_and_finds_its_answers_on_a_removable_drive.
      It fails on main too on this Mac, because it runs the recipe's shell with macOS's tools.
  • ruff check src tst passes.
  • Live, on an agent-environments-admin VM. I ran agent-env v0.9.1551 with this commit cherry-picked: main has
    changed the base computer since that release, so only the release has a published base. On it I registered 14 PSI
    whole-computer desktops, each under its own prefix (psi-tc-<spec>-full-desktop-).
    • The first composed the desktop and its 19 apps' one-app computers, in 42 min.
    • Every later one with the same apps reused all 20 images and built none. curbfinch-day's log has 20
      "reusing the image of the same key" lines and no "building the image" lines. Each took about 7.5 min, mostly
      probing the reused images.
    • Before this change, the same third registration rebuilt all 20, and two registrations had filled the
      242 GB builder.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The PR appears safe to merge.

Summary

Driver folders and service names now come from the driver’s declared name, so storing the same driver under different IDs no longer changes its image key.

  • Computer drivers keep the same folder when their storage ID changes.

Reviews (1) · Last reviewed commit: "fix(computers): a composed computer's ke..." · Reviewed by Greptile

…its driver is stored under

The composer installed a computer's driver in a folder named for the driver's id's last part, and named its programs
and their file after it. A driver stored under a registry prefix (a bundle registered with --prefix) has no "/" in its
id, so the whole prefixed id named the folder, went into the composed image's Dockerfile, and changed its key. The same
computer registered under two prefixes then shared no compose: each registration composed every computer again,
the desktop and each app's one-app computer.

The folder is now named for the name the driver's class declares (@computer_driver(name=...)), as an app's is for its
environment name. Every shipped driver declares the name of its folder, so a computer composed of one keeps its key.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale marked this pull request as ready for review November 17, 2026 23:43
@earakely-scale
earakely-scale requested a review from a team as a code owner November 17, 2026 23:43
@earakely-scale
earakely-scale merged commit 10adacc into main Nov 18, 2026
36 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/driver-folder-by-declared-name branch November 18, 2026 00:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant