Package resolution and environment builds
Hermes turns declared Python requirements and selected features into a checked, isolated runtime. It combines the core project, enabled extras, and eligible plugin requirements in a fresh workspace, then publishes a complete environment only after validation; separate tool and side-environment builds follow the same ownership model without changing the live application selection.
Package declarations
Package declarations define the inputs that Hermes may resolve. The root project keeps dependencies needed by every session in pyproject.toml, while optional dependencies group feature-specific requirements and dependency groups keep development and test tools out of runtime environments. The committed uv.lock supplies the reviewed resolution for Hermes itself; pm/lock.json separately pins managed binaries and their artifacts. References: pyproject.toml• L5-20, pyproject.toml• L225-261, pyproject.toml• L557-576, pyproject.toml• L628-680, pm/lock.py• L1-18
Hermes treats an extra as a named feature selection, not as an arbitrary package request. A feature is available when its anchor imports, and platform gates can refuse a feature before resolution when its required packages cannot run on the current target. This keeps optional providers and heavy native stacks out of the base environment until they are needed. References: pm/extras.py• L1-7, pm/extras.py• L16-70, pm/extras.py• L92-161, pm/features.py• L67-93
Dependency and extra selection
The application environment uses one recorded union of core dependencies, selected extras, and enabled plugin members. A sync carries forward still-declared features, adds explicitly requested features, and respects recorded user declines; a deliberate request can opt a declined extra back in. A bundle can also provide a baseline feature list, which becomes fixed when lazy installation is disabled. References: pm/install.py• L683-729, pm/install.py• L732-757, pm/install.py• L807-820, pm/install.py• L849-878, pm/features.py• L1-13
When a feature is first used, Hermes checks its anchors before it asks PM to sync. An interactive caller can approve the install, while a running prompt session does not read from its input stream. If the new generation cannot be adopted by the current process, Hermes reports that a restart is required instead of changing imports underneath that process. References: pm/extras.py• L182-238, pm/environments.py• L425-443
Plugin Python requirements join this same resolution only when the plugin is selected and declares installable dependencies. PM copies the core and plugin inputs into a generation-owned workspace, removes plugin development groups and unselected extras, and keeps only the source entries that apply to the selected runtime. A plugin with no build backend becomes a unique metadata member so two same-named plugins cannot collide. References: pm/workspace.py• L37-63, pm/workspace.py• L487-532, pm/workspace.py• L599-664
Workspace construction
Each environment candidate is built from a writable snapshot rather than from the shipped source or a live plugin tree. The snapshot carries the project metadata, package sources, selected plugin members, and a seed lock; the resolver narrows plugin solving to the platform and architecture of the interpreter that will install the generation. Core's release-age rule is enforced when Hermes creates its committed lock, not again on a user's machine. References: pm/workspace.py• L89-190, pm/workspace.py• L215-242, pm/AGENTS.md• L21-31
The normal application path creates a new generation under the installation's dependency state. It creates the virtual environment, resolves when plugin members require it, synchronizes all workspace packages, and checks the result before the caller records it as selected. A repair instead replays the saved workspace and lock, so it can restore the recorded graph without trusting changed manifests or silently dropping plugin dependencies. References: pm/packages.py• L469-571, pm/workspace.py• L714-749
This diagram shows how declarations become a selected runtime generation.
flowchart LR
A[Core manifest and lock] --> C[Selection union]
B[Extras and enabled plugins] --> C
C --> D[Writable workspace]
D --> E[Fresh environment]
E --> F[Dependency sync]
F --> G[Validation]
G --> H[Record selected generation]
Installation caching
Hermes uses two different caches for two different jobs. The managed tool store holds realized binary entries and their facts, while the shared uv cache holds package data that multiple profiles and generations can reuse. Neither cache is the live selected environment. References: pm/__init__.py• L1-11, pm/packages.py• L394-466, pm/install.py• L87-113
Tool installation is content-addressed by the lock's target artifact hashes. PM stages downloads in scratch space, unpacks and verifies them, then publishes the entry and records its digest. A dependency chain is installed as a unit, so a dependent tool does not appear on PATH when one of its required tools is missing. References: pm/install.py• L434-521, pm/install.py• L1070-1133
The uv cache can be seeded from a shipped payload and merged into the writable machine cache. The seed is marked only after a complete merge and is tied to the lock digest, so a new payload or changed link layout is merged again. A partial transfer or incomplete seed stays retryable instead of becoming a false cache hit. References: pm/packages.py• L333-466
Environment validation
Validation checks both package compatibility and the identity of the environment that will run Hermes. PM runs uv pip check against the generation's lock and accepts only mismatches explained by recorded lock overrides; repair also runs startup import checks in the candidate interpreter. The live process never validates a candidate by importing it into itself. References: pm/environment.py• L612-631, pm/recovery.py• L12-50, pm/packages.py• L557-571
Currency is a stamp comparison over the lock, selected extras, Python pin, and plugin member inputs. A current stamp allows a no-op sync; a changed input causes a new generation. Startup uses the recorded selection and a cheap state check, while explicit install and doctor paths can perform stronger byte and artifact checks. References: pm/packages.py• L490-510, pm/install.py• L648-729, pm/install.py• L299-305
Isolated environment builds
Explicit builds serve callers that need a fresh environment without changing Hermes's selected application environment. A project build can use the committed lock or resolve first; a requirements build can use a wheelhouse and an optional lock for its overrides. The destination must be new, and a failed build removes only the output claimed by that invocation. References: pm/client.py• L290-305, pm/build_operations.py• L44-99, pm/build_env.py• L37-141
Side environments and Python tools have their own names and selections. They return an interpreter or executable path, retain the previous generation while a replacement is built, and do not add their packages to the application environment. References: pm/client.py• L332-365, pm/operations.py• L118-171, pm/build_operations.py• L102-122
Recovery behavior
PM protects the last usable selection until a replacement is complete. The new generation is validated first, its files are flushed, and the selection record is written last. If publication fails, the candidate is removed and the prior selected generation remains. Runtime startup can recover an interrupted publication before it imports application dependencies. References: pm/install.py• L326-369, pm/install.py• L823-847, pm/environments.py• L263-305
Transient failures and invalid package graphs take different paths. Resolver conflicts and package build failures are reported as distinct errors; a failed download or local error is not mislabeled as a conflict. A corrupt uv cache entry is purged and the install retries a bounded number of times, while an invalid wheel after a fresh fetch points to the source rather than looping. References: pm/environment.py• L35-119, pm/environment.py• L465-526, pm/uv_cache_health.py• L25-69
Carried extras from a pre-PM environment receive special recovery treatment. If a carried native feature cannot build because a required tool is currently missing, PM leaves it out and records why; a transient fetch failure keeps the feature in the selection and fails the update so a later attempt retries it. A user-requested extra still fails the operation when it cannot build. References: pm/install.py• L972-999, pm/extras.py• L312-346
Receipts make every sync outcome visible to the CLI and other product surfaces. They record the selected feature list, rebuild result, warnings, refusal reason, and final outcome, including no-op syncs and policy refusals. References: pm/receipt.py• L1-9, pm/receipt.py• L132-215, pm/receipt.py• L227-258, pm/install.py• L949-1004
Change checklist
When these files or sections are changed, remember to consider these:
- Keep pyproject.toml, uv.lock, and the extra platform-gate table aligned. A declared extra can otherwise appear selectable while its anchor cannot run on the target.
- Keep the selected-extra stamp inputs aligned with workspace member hashing. A plugin declaration or source change must force a new generation.
- Keep repair records tied to the saved workspace and lock. Repair must not fall back to edited live plugin manifests or silently produce a smaller graph.
- Keep cache seed markers tied to the lock and seed format. A new payload cache must merge even when the lock digest is unchanged.
- Keep validation and selection publication ordered. A facts record must never name an environment that has not passed its checks and durable write step.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| An extra is selected on a platform blocked by its gate | Resolution can fail or install an unusable feature | PM checks the declared platform marker before sync and refuses the extra |
| A plugin's runtime dependency conflicts with the core or another selected member | The candidate environment is not published and the current selection stays active | PM resolves the complete union in a fresh workspace and classifies resolver conflicts |
| A machine stop leaves a damaged wheel in the uv cache | Every later sync can fail on the same cached bytes | PM identifies cache-integrity errors, purges the named entries, and retries within a bound |
| A dependency build fails during a carried legacy-extra migration | A feature may be left out or the whole update may fail, depending on whether the failure is permanent or transient | PM records permanent carried omissions and retries transient failures without publishing a partial environment |
| A process continues after a new generation is selected | It keeps its old imports and does not see newly installed packages | PM reports restart required and only selects environments during process startup |
| A selection record is written before its environment is durable | A power loss can point startup at a partial generation | PM flushes the candidate first and writes the selection record last |
Key files
| File | Why to read it |
|---|---|
| pyproject.toml | Core dependencies, optional features, development groups, platform gates, and resolver policy. |
| pm/extras.py | Feature anchors, platform support, lazy selection, and declined-extra handling. |
| pm/install.py | Application selection, sync policy, stamps, locks, publication, and recovery coordination. |
| pm/packages.py | The managed venv package and the shared uv cache used by environment builds. |
| pm/workspace.py | Core and plugin workspace snapshots, member metadata, lock seeding, and target narrowing. |
| pm/environment.py | PM's environment engine, resolver execution, validation, and cache recovery. |
| pm/environments.py | Installation identity, generation paths, selected-environment lookup, and process startup adoption. |
| pm/build_operations.py | Explicit project, requirements, and tool environment builds that remain separate from live selection. |
| pm/recovery.py | Candidate startup checks and repair or refresh behavior after damaged or replaced inputs. |
| pm/uv_cache_health.py | Detection and cleanup rules for corrupt cached package entries. |
| pm/receipt.py | Machine-readable sync outcomes used by status and update surfaces. |