Introducing a new way to review your PRs.

Read the announcement

nousresearch / hermes-agent

The agent that grows with you

View on GitHub

38 documents · Updated Nov 20, 2026

docs / package-resolution-and-environment-builds

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

TriggerConsequenceGuard
An extra is selected on a platform blocked by its gateResolution can fail or install an unusable featurePM checks the declared platform marker before sync and refuses the extra
A plugin's runtime dependency conflicts with the core or another selected memberThe candidate environment is not published and the current selection stays activePM resolves the complete union in a fresh workspace and classifies resolver conflicts
A machine stop leaves a damaged wheel in the uv cacheEvery later sync can fail on the same cached bytesPM identifies cache-integrity errors, purges the named entries, and retries within a bound
A dependency build fails during a carried legacy-extra migrationA feature may be left out or the whole update may fail, depending on whether the failure is permanent or transientPM records permanent carried omissions and retries transient failures without publishing a partial environment
A process continues after a new generation is selectedIt keeps its old imports and does not see newly installed packagesPM reports restart required and only selects environments during process startup
A selection record is written before its environment is durableA power loss can point startup at a partial generationPM flushes the candidate first and writes the selection record last

Key files

FileWhy to read it
pyproject.tomlCore dependencies, optional features, development groups, platform gates, and resolver policy.
pm/extras.pyFeature anchors, platform support, lazy selection, and declined-extra handling.
pm/install.pyApplication selection, sync policy, stamps, locks, publication, and recovery coordination.
pm/packages.pyThe managed venv package and the shared uv cache used by environment builds.
pm/workspace.pyCore and plugin workspace snapshots, member metadata, lock seeding, and target narrowing.
pm/environment.pyPM's environment engine, resolver execution, validation, and cache recovery.
pm/environments.pyInstallation identity, generation paths, selected-environment lookup, and process startup adoption.
pm/build_operations.pyExplicit project, requirements, and tool environment builds that remain separate from live selection.
pm/recovery.pyCandidate startup checks and repair or refresh behavior after damaged or replaced inputs.
pm/uv_cache_health.pyDetection and cleanup rules for corrupt cached package entries.
pm/receipt.pyMachine-readable sync outcomes used by status and update surfaces.