Skip to content

feat(bundle): a run or registration composes only the computer envs its tasks deploy - #792

Merged
earakely-scale merged 3 commits into
mainfrom
edgararakelyan/fd-6256-hb519-a-run-or-registration-composes
Nov 19, 2026
Merged

earakely-scale merged 3 commits into
mainfrom
edgararakelyan/fd-6256-hb519-a-run-or-registration-composes

Conversation

@earakely-scale

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

Copy link
Copy Markdown
Collaborator

What

agent-env run and bundle register now compose only the computer envs a bundle's tasks deploy.

Before this, they composed every computer env a bundle wrote. A computer app that names a computer and driver can be deployed alone, so it is a computer env too. A desktop of N such apps therefore composed N + 1 computers, though its task deploys only the desktop. For the full PSI desktop (19 apps) that was about an hour of Modal VM composes on dev, most of it for composes no deploy used.

This PR:

  • Finds the envs to compose (_composed_envs in bundle/materialize.py):
    • each env a task's steps name, and each env those hold, such as a multi env's computers. It doesn't go into a computer env's own apps and driver, which run inside it;
    • and each env pulled in from an installed bundle, such as chromium. Every bundle shares that env's one write, and a local run can't compose a stored env at its first deploy (below), so the registration that writes it leaves it deployable.
  • Writes every other computer env uncomposed (AuthoringContext.compose, passed to ComputerEnv.put(compose=...) by ComputerEnv and ComputerAppEnv). Its first deploy composes it (compose_unstarted), as it already does for a form no compose started, and agent-env env build still composes it on demand.
  • Skips the rest of the compose path for those envs too: the recompose of a reused version (_compose_reused), and fix(bundle): register fails when a computer env it writes has no build a deploy can boot #758's check that a computer env has a build a deploy can boot. An app no task deploys has no build, and that's expected now.
  • Keeps a bundle with no tasks as it was. A shipped bundle of apps or bases composes every computer env, so bundle register still leaves each one deployable alone.
  • AGENTS.md says this where it describes a computer env's compose.

FD-6256, under FD-6188.

A trade-off to know: a local agent-env run doesn't compose a registered env at its first deploy, since the run's fence refuses its record (computers/README.md says so, and the deploy names agent-env env build). So a local bundle run that names, by its registry id, an app registered only as part of a desktop now refuses at that deploy:

psi-6256b-shelfway-app has no ready build to deploy; its builds are none yet; compose it with: agent-env env build --id psi-6256b-shelfway-app

On main that registration composed the app, so the run deployed it. A stored task run (agent-env task run) and the hub's workers compose it at that first deploy, as the issue asks. This is the rule #759 already follows for the forms a registration leaves to other providers.

For the docs: where the docs describe what bundle register and agent-env run compose, they can say that each composes only the computer envs its tasks deploy, and that any other one composes at its first deploy.

Proof

  • Tests (tst/unit/bundle/computer_env_folder_test.py, writing a bundle through materialize, as agent-env run does):
    • A desktop of apps that each name a computer: only desktop composes. When the task deploys one app alone, only that app composes.
    • A multi env holding a computer: the computer composes with it, but not that computer's apps.
    • A bundle with no tasks: every computer env composes, each deployable alone.
    • A reused app no task deploys isn't composed again, nor said to be.
  • Tests (tst/unit/bundle/register_test.py):
    • A registration of the desktop composes desk-desktop alone. On main it composes desk-mail, desk-notes and desk-desktop.
    • A desktop holding the installed chromium as an app composes chromium too. Without the installed-bundle clause, only desk-desktop composes.
  • Without the fix, the desktop, multi env, reused-app and desktop registration tests fail. The app-alone and no-tasks tests pass either way, as the guards they are should.
  • Suites: tst/unit/bundle, env, cli and task gave 4,706 passed. One test fails on macOS before and after this change (test_disk_recipe.py::test_a_windows_install_...). Ruff is clean.
  • Live, on an agent-environments-admin VM (amd64, local Docker), the issue's case: PSI's whole-computer desktop for the Shelfway lamp refund (19 apps), staged with PSI's workaround switched off, so every app keeps its computer and driver.
    • bundle register --prefix psi-6256b- --sandbox local --no-emulate: exit 0 in 13.7 min, with one compose, envs/desktop (container/amd64: ready (13 min 18 s)). sp#2212's proof, with the workaround on, composed the same one; main without it composes 20.
    • The store afterwards: the desktop has its builds, and each app has none. For example, psi-6256b-gatelark-app has no composed records.
    • The app alone, as a stored task (a bundle whose task is deploy_env of psi-6256b-shelfway-app, registered with no composes, then agent-env task run): it composed the app on that first deploy (container/amd64 ready at 23:04:04, after the registration) and deployed it. Exit 0 in 97 s, torn down.
    • The app alone, as a local bundle run, before that: refused as the trade-off above says, naming agent-env env build --id psi-6256b-shelfway-app. Once composed, the same run deployed it in 4.2 s, composing nothing.
    • A first run of this proof filled the VM's disk during the desktop's build. It composed envs/desktop alone too.

Not here: a compose at deploy on a local sandbox tries every arch, without --no-emulate. On this amd64 VM, the app's container/arm64 was recorded failed (this machine can't build linux/arm64: its Docker has no emulation for it), where a registration with --no-emulate records skipped. That's compose_unstarted as it is on main; this change only makes it the path for more envs.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The PR appears safe to merge with the documented limit on local runs of unbuilt registered apps.

Summary

This PR avoids building standalone computers for apps that only run inside a desktop.

  • Bundle runs compose the computer environments their tasks deploy.

No new actionable issues found. earakely-scale explicitly accepts that a local run of an unbuilt registered app needs agent-env env build, because local runs cannot write that registered env's build records.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    P[Planned bundle] --> T{Has tasks?}
    T -->|No| A[Compose every computer env]
    T -->|Yes| R[Follow task env references]
    R --> C[Include computers held by non-computer envs]
    C --> S[Stop at each computer's apps and driver]
    S --> I[Also include pulled installed envs]
    I --> B[Compose selected computers]
    I --> U[Save other computers uncomposed]
    U --> D[Compose on first deploy where writes are allowed]
Loading

Reviews (2) · Last reviewed commit: "Merge origin/main into edgararakelyan/fd..." · Reviewed by Greptile

earakely-scale and others added 2 commits November 18, 2026 14:23
…ts tasks deploy

An app that names the computer and driver it deploys on alone is a computer too, so a run or registration of a desktop
of N such apps composed N + 1 computers, though its task deploys only the desktop: about an hour of Modal VM composes on
dev for the 19-app PSI desktop. Now each composes only the envs its tasks deploy: each env a task's steps name, and
each env those hold, but not a computer env's own apps and driver, which run inside it. Any other computer env is
written uncomposed and composes at its first deploy (compose_unstarted), or with agent-env env build. A plan with no
tasks composes every computer env, each deployable alone, as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…bundle still composes

The shared store's one write of an installed bundle's env, such as chromium, is the one every bundle reads, and a local
run can't compose a store's env at its first deploy, so the registration that writes it leaves it deployable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale requested a review from a team as a code owner November 18, 2026 23:07
…tion-composes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale merged commit 7943c00 into main Nov 19, 2026
61 of 63 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/fd-6256-hb519-a-run-or-registration-composes branch November 19, 2026 17:26
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