Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
Merge remote-tracking branch 'origin/dev' into fix/issue-825-storage-layout-v2
Alfredo Lopezb1178e64586f
diff --cc docs/deploy/production.mdindex fba84a8c3,5a9af9ac7..3d14eed13--- a/docs/deploy/production.md+++ b/docs/deploy/production.md@@@ -89,9 -393,10 +393,11 @@@ modified MPL-licensed files. See [LICEN## Related+ - [Releases and upgrades](releases-and-upgrades.md)+ - [Configuration reference](../reference/configuration.md)+ - [Minikube setup](minikube.md)- [WorkflowRecipes operations](workflow-recipes-guide.md)- - [Plugin Workload SDK upgrade and policy migration](plugin-workload-sdk-upgrade.md)+- [Host PVC layout upgrade from v0.10.x / v0.11.x](host-pvc-layout-upgrade.md)- [Member invitations on self-hosted](../how-to/member-invitations-self-hosted.md)- [Architecture / topology](../architecture/platform-topology.md)- [FAQ](../faq.md)diff --cc docs/deploy/releases-and-upgrades.mdindex 000000000,b7f8e8194..e7112c313mode 000000,100644..100644--- a/docs/deploy/releases-and-upgrades.md+++ b/docs/deploy/releases-and-upgrades.md@@@ -1,0 -1,234 +1,235 @@@+ # Releases and upgrades++ How evenfire is versioned and released, how to run a specific release, and what+ to read before you upgrade.++ ## Version numbers++ evenfire uses two kinds of version number. They mean different things.++ | Version | Where it lives | What it means |+ | --------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |+ | **Release** `vX.Y.Z` | Git tag, image tag `ghcr.io/evenfire-ai/<image>:vX.Y.Z` | The repository release. Released images, the Desktop App, and the ghcr image pin all carry this one number. |+ | **Desktop App** `X.Y.Z` | `desktop-app/package.json` | Always equal to the release version. Only the release script writes it. |+ | **Service counter** `0.1.N` | `version` in each service's `package.json` (`external-rest-api`, `rpc-proxy`, `control-api`, …) | A per-service change counter. The pre-commit hook bumps the patch number on every commit that touches that service. It is not a release number. |++ So `v0.10.0` is a release, and `external-rest-api` `0.1.100` only means that+ service has changed about a hundred times. Do not compare service counters+ across services, and do not use them to pick a release.++ ### How service counters are bumped++ The tracked pre-commit hook (`.githooks/pre-commit`) runs+ `npm run version:staged`. For every package root that has staged changes and+ whose `package.json` version still equals `HEAD`, it raises the patch number by+ one and stages `package.json` and `package-lock.json`. Run+ `make install-git-hooks` (or `npm run install-git-hooks`) once to enable the+ hook.++ Two counters are also published to clients. `external-rest-api/src/releaseManifest.ts`+ declares `externalRestApiVersion` and `rpcProxyVersion`, so the hook regenerates+ and stages that file when either package is bumped. CI checks both rules on+ every pull request:++ - `update-desktop-release-manifest.mjs --validate-only` fails if the manifest+ disagrees with the package versions.+ - `validate-release-version-bumps.mjs` fails if code under `external-rest-api/`+ or `rpc-proxy/` changed but that package's version did not.++ `desktop-app` is not a hook package root, so the hook never bumps it. See+ [CONTRIBUTING.md](../../CONTRIBUTING.md#the-pre-commit-hook-may-edit-your-commit)+ for what the hook does to your commits.++ ## How a release is made++ Images are built by `build-publish.yml`: automatically on every push to `dev`,+ or when a maintainer runs that workflow by hand (`workflow_dispatch`, optionally+ with `build_all`). A release never rebuilds them. It copies images that were+ already built to the release tag.++ ```text+ push to dev ──► build-publish.yml ──► ghcr.io/evenfire-ai/<image>:sha-<7> and :latest+ (multi-arch: linux/amd64 + linux/arm64)++ prepare-release.mjs ──► release-prep commit ──► tag vX.Y.Z+ │+ ▼+ release-images.yml ──► :vX.Y.Z (and :stable)+ ```++ 1. **Continuous builds.** On every push to `dev`,+ [`build-publish.yml`](../../.github/workflows/build-publish.yml) rebuilds only+ the images whose source paths changed. Each image is built natively for+ `linux/amd64` and `linux/arm64` and merged into one manifest list tagged+ `sha-<7 chars>` and `latest`. The manifest list records the commit it was+ built from in the `org.opencontainers.image.revision` annotation. Pushes to+ `main` do not build images.+ 2. **Cut the release.** A maintainer runs:++ ```bash+ node scripts/release/prepare-release.mjs --version X.Y.Z --release-id vX.Y.Z \+ [--minimum-desktop-version A.B.C]+ ```++ It refuses a version that is not greater than the last committed Desktop App+ version. It writes every release coordinate (listed in+ [`release-coordinates.mjs`](../../scripts/release/release-coordinates.mjs)):++ | Coordinate | Rule |+ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------- |+ | `desktop-app/package.json` and `package-lock.json` | Equals `X.Y.Z` |+ | `releaseManifest.desktopVersion` | Equals `X.Y.Z` |+ | `releaseManifest.releaseId` | Set explicitly (never `local`) |+ | `releaseManifest.minimumDesktopVersion` | A floor, at most `X.Y.Z`. Changes only when `--minimum-desktop-version` is passed. |+ | `releaseManifest.externalRestApiVersion` / `rpcProxyVersion` | Equal their own `package.json` counters |+ | `newTag` of every row in `deploy/components/ghcr-images` | Equals `vX.Y.Z` |++ `node scripts/release/validate-release-tag.mjs --version X.Y.Z` checks that+ all coordinates agree. It does not check that the images exist, because they+ are only created when the tag is pushed.++ 3. **Tag.** Pushing a `v*` tag to `evenfire-ai/evenfire` starts+ [`release-images.yml`](../../.github/workflows/release-images.yml). For each+ published image in [`deploy/images.json`](../../deploy/images.json),+ [`resolve-release-images.mjs`](../../scripts/release/resolve-release-images.mjs)+ resolves `:latest` to a digest once, then refuses the image if:+ - it has no revision annotation;+ - the revision it was built from is not an ancestor of the tagged commit;+ - its source paths changed between that revision and the tagged commit.++ [`promote-release-images.sh`](../../scripts/release/promote-release-images.sh)+ then checks that the digest is a manifest list with both `amd64` and `arm64`,+ and copies it (with `crane copy`) to `:vX.Y.Z`. For a strict `vX.Y.Z` tag it+ also copies it to `:stable`. If any image is refused, the job fails, but the+ other images are still copied, so a failed run can leave a partial release.+ A manual+ `workflow_dispatch` run is a dry run: it prints what it would promote and+ copies nothing.++ The hosted evenfire service deploys from these same images through a separate,+ private pipeline. That pipeline is not part of this repository.++ ### What is fixed and what moves++ | Tag | Moves? |+ | --------------------- | -------------------------------------------------------------------------------------------------- |+ | `:latest`, `:sha-<7>` | `:latest` moves on every `dev` build of that image. `:sha-<7>` names one build. |+ | `:vX.Y.Z` | Written by the release workflow for that tag. Nothing in normal operation rewrites it. |+ | `:stable` | Moves to whichever strict `vX.Y.Z` tag was promoted last (a patch to an older line moves it back). |+ | `@sha256:…` digest | Never moves. Use a digest when you need a byte-for-byte guarantee. |++ The release workflow has no guard that stops a second run from writing+ `:vX.Y.Z` again. If you need an image that cannot change, pin the digest.++ ## Run a specific release++ ### Minikube++ `make minikube-setup` pulls images from `ghcr.io/evenfire-ai` by default+ (`IMAGE_SOURCE=ghcr`). The `minikube-ghcr` and `minikube-no-uis-ghcr` overlays+ add the [`ghcr-images`](../../deploy/components/ghcr-images/kustomization.yaml)+ component. It rewrites the 25 images that are both published and deployed to+ minikube from their local `clerum/<name>` refs to+ `ghcr.io/evenfire-ai/<name>:vX.Y.Z`. It also rewrites image refs inside+ Deployment env values, such as the images HCC uses to start child pods.++ To run a release, check out its tag and run setup:++ ```bash+ git checkout vX.Y.Z+ make minikube-setup+ ```++ `MINIKUBE_IMAGE_TAG` overrides the pinned tag for one run. It edits a temporary+ copy of the deploy tree, never the committed file:++ ```bash+ MINIKUBE_IMAGE_TAG=latest make minikube-setup # newest dev builds+ MINIKUBE_IMAGE_TAG=v0.9.0 make minikube-setup # an older release+ ```++ On a branch where the release-prep commit has landed but the tag has not been+ promoted yet, the pin names images that do not exist yet. In that window,+ re-run with `MINIKUBE_IMAGE_TAG=latest`, as+ [the quickstart](../get-started/quickstart.md) explains.+ To build every image from source instead, use `make minikube-setup-local`.+ See [minikube.md](minikube.md) for the full setup.++ ### Your own cluster++ [`deploy/base`](../../deploy/base) refers to images by local `clerum/<name>`+ names. To run published images, rewrite them in your own kustomize overlay:++ - include `deploy/components/ghcr-images` as a component, which pins the 25+ minikube-deployed images to the release tag of the commit you check out; or+ - write your own `images:` block with `newName: ghcr.io/evenfire-ai/<name>` and+ a `digest:` per image.++ Do not deploy `:latest` or `:stable` to a cluster you care about. Every image+ in a cluster should come from the same release.+ [`deploy/images.json`](../../deploy/images.json) lists every image, whether it+ is published (`published`), and whether minikube deploys it+ (`deployed_to_minikube`). Images such as `mcp-host-desktop`,+ `clerum-workflow-base`, and `playwright-server` are published but are not in+ the component.++ The CRD Helm chart ([`charts/clerum-crds`](../../charts/clerum-crds)) has its+ own chart version. It does not follow the release number. Always apply the CRDs+ from the same checkout as your images.++ ## Desktop App versions++ The Desktop App version is the release version, and its GitHub release tag is+ the same `vX.Y.Z` tag. There is no separate `desktop-app-<version>` tag.++ The External REST API serves `GET /api/v1/desktop/release` (authenticated). It returns+ the values in `releaseManifest.ts` plus `releaseTag` (`v<desktopVersion>`) and+ `releaseUrl`. `releaseUrl` is built from `EXTERNAL_REST_API_DESKTOP_RELEASE_BASE_URL`,+ which defaults to `https://github.com/evenfire-ai/evenfire/releases`. Point it+ at your own releases page if you ship your own builds.++ When the installed app is older than `minimumDesktopVersion`, the app shows+ **Desktop update required** and links to `releaseUrl`. See+ [Use the Desktop App](../how-to/use-the-desktop-app.md).++ No workflow in this repository builds or signs Desktop App installers. To build+ one yourself, use the Electron Forge scripts in `desktop-app/package.json`+ (`make:mac:arm64`, `make:mac:x64`, `make:windows:x64`, `make:windows:arm64`,+ `make:linux:x64`, `make:linux:arm64`) with Node 24, after `npm ci` and+ `npm run verify:electron`.++ ## Upgrade notes++ Read the notes for every release you skip over, not only the target release.++ ### General order++ 1. **Back up the database** (`control-postgres`) before any upgrade.+ 2. **Apply the CRDs first.**++ ```bash+ KCTX=<your-context> # the cluster you are upgrading; never rely on the current context+ kubectl --context "$KCTX" apply -f ./charts/clerum-crds/crds/+ ```++ `helm upgrade` does not update files in a chart's `crds/` directory, so you+ must apply them yourself. The order matters: the API server drops fields+ that the installed CRD schema does not know, without an error. If new+ `control-api` or `mcp-host` pods write a new field (for example+ `spec.guardrails` or `spec.llmPolicy` on a Host) while the old CRD is still+ installed, that field is silently lost. The `ROLLOUT ORDER — CRD FIRST`+ comments in+ [`charts/clerum-crds/crds/host.yaml`](../../charts/clerum-crds/crds/host.yaml)+ mark these fields. See also the [CRD reference](../crds/README.md).++ 3. **Then roll out the images** for the new release, all from the same tag.+ 4. **Follow any feature-specific runbook** below.++ ### Feature-specific notes++ | Note | Read it when |+ | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |+ | [Workflow output PVC upgrade](workflow-output-pvc-upgrade.md) | You use WorkflowRecipes with `spec.output.destination: pvc`. The default PVC is now one per parent recipe. |+ | [Plugin Workload SDK upgrade and policy migration](plugin-workload-sdk-upgrade.md) | You use the Plugin Workload SDK. It has a required order with the SDK turned off during the upgrade. |+ | [GFS permission-store credential lifecycle](gfs-permission-store.md) | You run the Global File System. It covers provisioning, rotating, and recovering the `gfs_controller` credential. |++| [Host PVC layout upgrade](host-pvc-layout-upgrade.md) | You upgrade from v0.10.x or v0.11.x and have created stateless Hosts. Run the inventory before the upgrade. |diff --cc mcp-host/package-lock.jsonindex de6cc46c5,2c4557074..3e1d03d9c--- a/mcp-host/package-lock.json+++ b/mcp-host/package-lock.json@@@ -1,12 -1,12 +1,12 @@@{"name": "clerum-mcp-host",- "version": "0.1.581",- "version": "0.1.561",++ "version": "0.1.582","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-mcp-host",- "version": "0.1.581",- "version": "0.1.561",++ "version": "0.1.582","license": "SEE LICENSE IN LICENSE","dependencies": {"@anthropic-ai/sdk": "^0.32.0",diff --cc mcp-host/package.jsonindex f4bdd8d7c,cd50b32bf..7eef2e7d8--- a/mcp-host/package.json+++ b/mcp-host/package.json@@@ -1,6 -1,6 +1,6 @@@{"name": "clerum-mcp-host",- "version": "0.1.581",- "version": "0.1.561",++ "version": "0.1.582","description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude","main": "dist/main.js","engines": {