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-management-and-distribution

Package management and distribution

Package management and distribution provide one path from pinned third-party inputs to usable Hermes environments and published releases. The system resolves packages for the current platform, verifies and stores their bytes, builds dependency environments that include selected plugins, and moves tested release artifacts through an ordered publication process.

System boundaries

The subsystem has two related responsibilities. Package management makes a local or build-time environment match declared dependency state. Distribution turns tested application builds into immutable artifacts and advances public update channels only after their identity and integrity are checked.

The package manager owns package pins, target support, installed state, tool exposure, and recovery. The release system owns native package receipts, candidate manifests, public feeds, Docker release identities, and channel promotion. They meet at the build boundary: release jobs use the package manager to create repeatable build inputs, then publish the resulting bytes without rebuilding them during promotion.

Package acquisition

Package pins

Package pins define the version and verified artifact set for each supported target. A lock entry carries resolved URLs and SHA-256 values, so an install does not need to re-create a download decision from a changing upstream index. Update checks may inspect upstream release indexes, but a real update changes the lock only after it finds a version or target-specific artifact that all required targets can use. (Related page: package resolution and environment builds)

References: pm/lock.py• L1-18 pm/update.py• L1-23 pm/package.py• L52-107

Artifact store

The artifact store is the shared byte source for installed tools and build operations. It keeps verified downloads by digest, stages package trees in scratch space, checks their expected layout and target architecture, then publishes each usable tree with an atomic move. This lets failed work leave the prior usable entry in place and lets several consumers reuse the same verified bytes.

The store also handles platform differences such as Windows, macOS, Linux, musl, and Android targets. A package can be unavailable on a target without being an error in the package definition; the resolver and callers must treat that gap as an explicit platform choice.

References: pm/store.py• L24-35 pm/store.py• L152-168 pm/store.py• L381-486 pm/package.py• L131-183

Installed state

Installed state records which lock identity is present and how that package changes the runtime environment. The record includes the store entry, target, artifact digests, realized tree digest, and environment contribution. Startup and diagnostics can therefore detect drift without downloading packages, while an explicit install can re-check the bytes and repair a changed entry.

References: pm/lock.py• L149-225 pm/lock.py• L241-279 pm/install.py• L299-305

Environment construction

Tool environments

Tools are installed from the same pinned store as application dependencies. Their dependency graph is walked before installation, and the resulting environment places complete managed tool chains ahead of host tools when Hermes runs commands. Internal package tools support setup and builds without becoming user-facing application roots.

References: pm/install.py• L563-645 pm/install.py• L1050-1133 pm/package.py• L52-71

Dependency environments

The project environment is a selected state, not just a directory. Its validity depends on the project lock, enabled extras, the selected plugin members, and the interpreter or platform that will install them. Hermes builds a fresh candidate generation, checks it, and records the generation only after it is ready. This prevents a failed dependency solve from replacing the active environment.

The environment can be rebuilt from the recorded dependency selection when its files are damaged or when a shipped code and lock set changes. Recovery validates the candidate with the candidate interpreter, so the repairing process does not rely on the environment it is repairing. (Related page: package resolution and environment builds)

References: pm/packages.py• L469-571 pm/install.py• L782-847 pm/recovery.py• L23-64 pm/recovery.py• L92-131

Plugin dependency union

Enabled plugins that declare Python packages join the core project as workspace members for one environment generation. Their source is copied into a writable build snapshot, and the generation stamp includes the member set and member content. A plugin change therefore causes a new solve even when the core lock and selected extras did not change. (Related page: package resolution and environment builds)

The following flow shows how a package or plugin input becomes an active environment or a release input.

flowchart LR
    A[Lock and package declarations] --> B[Target resolution]
    B --> C[Verified artifact store]
    C --> D[Tool environment]
    A --> E[Core project and enabled plugins]
    E --> F[Candidate dependency generation]
    D --> F
    F --> G[Validated active environment]
    D --> H[Build inputs]
    G --> H
    H --> I[Native release artifacts]

References: pm/workspace.py• L1-5 pm/workspace.py• L37-63 pm/workspace.py• L137-177 pm/packages.py• L490-510

Artifact distribution

Release candidates

Release jobs build native packages from an admitted source and stage them as candidate artifacts. Each package is recorded from its actual embedded identity and version. Receipts bind file paths, sizes, and digests to the release attempt, while a candidate manifest groups those receipts with smoke results and the source commit.

Promotion consumes that manifest instead of rebuilding or trusting workflow names. Windows, macOS, and Termux packages can be built by separate jobs, but the candidate assembly checks that the handoffs agree and that the candidate contains exactly the targets claimed by the release lanes.

References: scripts/…/release_artifacts.py• L76-156 scripts/…/release_artifacts.py• L179-248 scripts/…/channel_releases.py• L57-84

Release promotion

Stable publication is an ordered transaction over several delivery systems. A green build first leaves immutable versioned artifacts and receipts. The publication controller then validates the accepted candidate, writes public update feeds and package indexes, promotes Docker aliases, and advances the protected channel head. The final version tag records the custody of the accepted bytes.

Canary and one-off builds use separate channel or commit identities. They can publish diagnostics or preview feeds without changing the stable channel. A stable channel moves only when the release includes the complete desktop set that the channel serves.

References: scripts/…/release_artifacts.py• L255-309 scripts/…/release_artifacts.py• L359-395 scripts/…/channel_releases.py• L341-446 website/…/stable-releases.md• L1-7

Release recovery

Release recovery preserves the original claim, commit, lane set, receipts, and candidate bytes. A failed publication pass reruns the missing work and verifies each existing object before it continues. It does not replace accepted artifacts to repair a pointer, because the immutable receipt is the source of truth for what was tested.

The same principle applies locally. Package publication keeps the prior store entry available until the new entry and installed facts are committed. Environment recovery rebuilds the recorded graph and keeps the previous selected generation until the replacement passes validation.

References: scripts/…/channel_releases.py• L121-191 scripts/…/channel_releases.py• L236-256 pm/install.py• L326-369 pm/recovery.py• L53-64

Change checklist

When these files or sections are changed, remember to consider these:

  • A package pin change must remain consistent across every supported target, its artifact digest, and the package's target-specific layout checks.
  • A package environment contribution change must be reflected in recorded installed facts; otherwise activation can silently use an old PATH or runtime setting.
  • A plugin workspace input change must update the environment stamp inputs so the active generation cannot be reused for a different member set.
  • A release receipt or candidate-manifest schema change must remain compatible with candidate admission, materialization, promotion, and channel bootstrap readers.
  • A new release target must be added to the lane claim, handoff receipt set, candidate package set, and public feed rules as one contract.
  • A public pointer change must preserve the immutable artifact and read-back checks; pointers must never become the only record of accepted bytes.

Important failure modes

TriggerConsequenceGuard
A lock entry has no artifact for the current targetThe package cannot be installed or stagedTarget-aware lock validation and explicit package gaps
A downloaded archive has the wrong digest or unusable layoutThe new store entry is rejected and the prior entry remains availableDigest verification, package verification, and atomic store publication
Plugin members change without a new generation stampThe active environment can omit or retain the wrong plugin dependenciesMember content and identity are part of the environment stamp
A release receipt disagrees with the candidate manifestPublication stops before public feeds or channel heads moveReceipt digest checks and candidate validation
Publication fails after one service is updatedA later retry may see a partial release stateIdempotent read-back checks and immutable versioned objects
The recorded environment is damaged or no longer matches the source lockHermes may fail at startup or run with stale dependenciesFresh generation rebuild and candidate-interpreter validation

Key files

FileWhy to read it
pm/package.pyDefines the package contract, dependency relationships, target gaps, verification, and environment contributions.
pm/lock.pyDescribes the lock and installed-state identities that connect pins to realized bytes.
pm/store.pyShows the verified, shared, atomic artifact-store boundary.
pm/install.pyConnects dependency graphs, store entries, runtime environment activation, and rollback.
pm/packages.pyShows how tool packages and the project environment participate in the package graph.
pm/workspace.pyExplains how core and plugin sources become one dependency-solving input.
pm/recovery.pyDefines environment validation and recovery behavior.
scripts/…/release_artifacts.pyDefines candidate receipts, artifact materialization, feed publication, and promotion.
scripts/…/channel_releases.pyCoordinates protected channel admission, candidate matching, and release publication.
scripts/release.pyProvides the operator entry points for stable, canary, and one-off release flows.
.github/…/stable-release.ymlShows the build, acceptance, candidate, and publication stages of a stable release.
website/…/stable-releases.mdGives the operator-level release and recovery model.