Skip to content

feat(computer): key installs, known failures and app declarations by distribution as well as OS type - #553

Merged
earakely-scale merged 3 commits into
mainfrom
edgararakelyan/o2-install-keyed-by-distribution
Nov 9, 2026
Merged

earakely-scale merged 3 commits into
mainfrom
edgararakelyan/o2-install-keyed-by-distribution

Conversation

@earakely-scale

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

Copy link
Copy Markdown
Collaborator

Summary

A driver's install and known failures, and an app's declarations, were keyed by OS type alone ([install.linux], @linux(...)). So one driver or app couldn't install one way on Ubuntu (apt, X11, cua-driver 0.38) and another on Omarchy (pacman, Wayland, cua-driver 0.44 and Hyprland's plugin). They can now be keyed for one distribution, by its /etc/os-release ID, as <os>/<distribution>:

[install.linux]                       # every Linux without its own entry
services = [...]

[install."linux/omarchy"]             # Omarchy alone
python = "requirements-omarchy.txt"
services = [...]

[[known_failures."linux/omarchy"]]
check = "P6"
name = "..."
reason = "..."
@linux(distribution="omarchy", launch=..., settings=...)   # or @install("linux/omarchy", Linux(...), ...)
@linux(launch=...)
class Notes(ComputerAppEnvironment): ...
  • Replace, not merge. On that distribution its entry stands alone, and the OS type's applies everywhere else. A Linux waiver or an apt package never leaks onto Omarchy, and what installs is exactly what one table says.
  • One key and one lookup in the protocol's platform.py:
    • platform_key(os, distribution);
    • entry_for(by_platform, key): the distribution's entry, else the OS type's;
    • applies(keys, key), for install steps' and ready checks' os=, where one for an OS type runs on all of it. A step or check scoped to a distribution is accepted when that distribution or its OS type has an install.
  • The framework passes the computer's platform key (install.platform_of(base.os)) wherever it reads an app's or driver's declarations: gate 1, the composer, gate 3's known failures, boot's settings and ready timeout, and the computer provider. It keeps the bare OS type where it means the OS (native links, sites, trust files, os_type= to boot and probe).
  • On the computer, an app's class reads what's declared for the platform its computer was composed for: its distribution's before its OS type's.
    • For an app that declares an install, install step or ready check for a distribution, the composer sets AGENTENV_PLATFORM, the platform key it built the image for, in the app's services and install steps.
    • The protocol reads that before /etc/os-release (platform.detect()), so the app always acts on the install its image holds, even if a base's label and its image disagreed.
    • An app that declares nothing for a distribution reads the same either way and gets no variable, so existing images' keys don't change. Outside a composed computer (dev, tests) the app falls back to detect().
  • Refused at put:
    • a key that isn't an OS type or <os>/<distribution>;
    • an install or known failures for a distribution that no supports entry names, which would never apply (a misspelt "linux/omarcy", say).

Nothing changes for an env that declares no distribution: every lookup falls back to the OS type, as before.

Decided on FD-5339 (2026-11-09):

  • the key form is "linux/omarchy";
  • a distribution's entry replaces the OS type's rather than merging;
  • the composer tells the computer which platform it composed for (above).

Checking that a disk base's /etc/os-release matches its declared distribution belongs to O1 (FD-5338), at its builder boot.

Before registering Omarchy envs into a shared store, upgrade its readers. Code from before this PR fails to read a driver stored with a "linux/omarchy" install (KeyError in ComputerDriverEnv.from_dict), and silently drops an app's or known failure's distribution entry. The pacman half of FD-5339 (packages.pacman, the resolver in a booted base, the lock, the offline pacman -U) is a follow-up PR.

Docs: the drivers README (known failures and installs by distribution), the protocol README (@linux(distribution=...)), and AGENTS.md.

Testing

  • Unit tests:
    • installs() takes linux/omarchy with Linux's model and refuses malformed keys; for_os picks the distribution's entry, else the OS type's.
    • Gate 3, end to end: a linux/omarchy waiver isn't applied on an Ubuntu base. A linux/ubuntu waiver is, and replaces the linux entry there.
    • A driver bundle: it takes [install."linux/omarchy"] and [[known_failures."linux/omarchy"]] when supports names Omarchy, and refuses them, and a malformed key, before any write when it doesn't.
    • An app bundle with @linux(distribution="omarchy") and no Omarchy in supports is refused.
    • The composer: an app with a linux/ubuntu install step on an Ubuntu base gets AGENTENV_PLATFORM=linux/ubuntu in its install step and its supervisord conf. Apps that declare nothing for a distribution keep their exact Dockerfile and conf, as the existing tests assert.
    • The protocol:
      • an app reads Omarchy's launch, settings and ready checks on Omarchy and Linux's on Ubuntu or with no distribution;
      • a ready check for linux runs on Omarchy;
      • a check on an OS the app installs nothing for is refused;
      • @linux takes distribution;
      • an app reads AGENTENV_PLATFORM over what it detects;
      • a linux/ubuntu step or check on an app with only @linux is accepted and runs only on Ubuntu, and one whose distribution and OS type have no install is refused.
  • ruff check . is clean.
  • Locally the framework's env, driver, artifact, serialization, env-provider, shipped-bundle and app/driver bundle tests and the whole protocol suite pass: 3,815. Two tests fail the same way on main on this machine (a Sail provider test and a Windows disk-recipe test), and CI runs everything.

Part of FD-5339 (under FD-5336).

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The PR appears safe to merge; the remaining malformed-scope finding is non-blocking.

Fix All in CursorFindings

  1. P2 Malformed scopes silently skip work ▶
Fix with agent prompt
### Issue 1
packages/agentenv-protocol/src/agentenv_protocol/computer/app.py:628-629
`declaration()` now accepts malformed scopes such as `@install_step(os="linux/")` or `@ready_check(os="linux/ubuntu/extra")` when the app declares `@linux`. `entry_for` finds the Linux fallback, so these values pass the check. Neither value matches a valid computer platform, so the step or check is silently skipped everywhere.

Validate the scope’s format before checking for a matching install, and add tests for both decorators.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds distribution-specific installs, app declarations, and known failures with OS-level fallbacks.

  • Drivers can set installs and known failures for one Linux distribution.
  • Apps can declare different installs and behavior for each Linux distribution.
  • Computer images and apps use the platform they were composed for.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  B[Base OS and distribution] --> K[Platform key]
  K --> E{Distribution entry exists?}
  E -->|Yes| D[Use distribution entry]
  E -->|No| O[Use OS entry]
  D --> C[Compose app]
  O --> C
  C --> P[Pass AGENTENV_PLATFORM when needed]
  P --> R[App reads matching declaration]
Loading

Reviews (9) · Last reviewed commit: "fix(computer): tell an app the platform ..." · Reviewed by Greptile

@earakely-scale
earakely-scale requested a review from a team as a code owner November 9, 2026 05:49
earakely-scale and others added 3 commits November 8, 2026 22:28
…tion as well as OS type

A driver's env.toml can declare [install."linux/omarchy"] and [[known_failures."linux/omarchy"]]
beside [install.linux]: an entry for a base's distribution, its /etc/os-release ID, replaces its OS
type's there and only there. Gate 1, the composer and gate 3 take the most specific entry through one
lookup (install.for_os); a key that isn't an OS type or <os>/<distribution> is refused at put.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…fuse a distribution no supports names

An app declares for one distribution with @linux(distribution="omarchy", ...) or
@install("linux/omarchy", ...): on that distribution its install, launch, paths, skill and settings
replace the OS type's, and on the computer the class reads its platform's (platform_key, entry_for),
its distribution's before its OS type's. An install step or ready check's os= takes OS types or
distributions, one for an OS type running on all of it. The framework passes the computer's
platform, <os>/<distribution>, wherever it reads an app's declarations (gate 1, the composer, gate 3,
boot and the computer provider), and keeps the OS type where it means the OS (native links, sites,
trust files). A driver's install or known failures, or an app's install, for a distribution no
supports entry names is refused at put, as it would never apply.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…, and accept a distribution scope on its OS's install

An app's server and install steps picked its declaration by /etc/os-release, while the composer
picked its install by the base's distribution, so a base whose label and image disagree would run an
app half one way and half the other. For an app that declares an install, install step or ready
check for a distribution, the composer now sets AGENTENV_PLATFORM, the platform it composed for, in
its services and install steps, and the protocol reads it before what it detects; an app that
declares nothing for a distribution reads the same either way and its image is unchanged.

An install step or ready check scoped to a distribution is accepted when that distribution or its OS
type has an install, so @ready_check(os="linux/ubuntu") works on an app with only @linux. A
distribution key now takes the computer artifact's own pattern (DISTRIBUTION), and boot's helpers name
their parameter the platform they receive.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale force-pushed the edgararakelyan/o2-install-keyed-by-distribution branch from 815c43f to 81562ca Compare November 9, 2026 06:30
@earakely-scale
earakely-scale merged commit bfdcb20 into main Nov 9, 2026
35 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/o2-install-keyed-by-distribution branch November 9, 2026 06:47
Comment on lines +628 to +629
if unknown := [os_type for os_type in method.os or []
if entry_for(cls._installs, os_type) is None and os_type not in installed_os]:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Malformed scopes silently skip work

declaration() now accepts malformed scopes such as @install_step(os="linux/") or @ready_check(os="linux/ubuntu/extra") when the app declares @linux. entry_for finds the Linux fallback, so these values pass the check. Neither value matches a valid computer platform, so the step or check is silently skipped everywhere.

Validate the scope’s format before checking for a matching install, and add tests for both decorators.

Prompt To Fix With AI
This is a comment left during a code review.
Path: packages/agentenv-protocol/src/agentenv_protocol/computer/app.py
Line: 628-629

Comment:
**Malformed scopes silently skip work**

`declaration()` now accepts malformed scopes such as `@install_step(os="linux/")` or `@ready_check(os="linux/ubuntu/extra")` when the app declares `@linux`. `entry_for` finds the Linux fallback, so these values pass the check. Neither value matches a valid computer platform, so the step or check is silently skipped everywhere.

Validate the scope’s format before checking for a matching install, and add tests for both decorators.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Fix in Cursor Fix in Claude Code Fix in Codex

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