GAIA Sidecar Agent Release

Releasing a GAIA Sidecar Agent (frozen binary + npm)

How to ship a sidecar agent — a frozen, no-Python REST binary plus a thin npm client — to the GAIA Agent Hub and npm, via the tag-triggered CI release. The email agent is the reference: hub/agents/email/python/ + hub/agents/email/npm/ + .github/workflows/release_agent_email.yml.

This is a phased process with one hard human gate (the agent-publish environment). Stop and confirm before anything irreversible — pushing a release tag, approving the publish gate. Publishes are immutable per filename: a bad release is fixed by a new version, never an overwrite.

Status — the email pipeline has not yet cut a real release. hub/agents/email/npm/binaries.lock.json still carries placeholder PENDING-1648 hashes and #1648 is open, so the freeze→publish→fetch-verify path has never run end-to-end. Treat this skill as the design of record, not a paved road, until the first real release lands and fills the lock. Likewise the agent-publish environment + GAIA_HUB_TOKEN + hub vars are maintainer setup (workflow header) — verify they exist before relying on them.

Relationship to the author guide (read first)

docs/guides/hub-publishing.mdx is the author-facing guide for the standard distribution: a Python wheel published to the Hub + PyPI via gaia agent publish (or the no-token PR route). It owns the authoritative rules for the manifest, versioning, immutability, and the two publish routes — don't restate or contradict them here.

This skill covers the additional channel an agent like email layers on top: a frozen native binary + an @amd-gaia/agent-<id> npm client, released through release_agent_<id>.yml. An agent can ship one or both channels. Where the two overlap (manifest, version rules), the guide is the source of truth.

Releasing an agent that has never shipped before? Cutting the release is the last phase. An agent is not release-ready because its code runs — it needs a capability-truth audit, a real scorecard, the doc bundle, and a day-one usability check first. Use porting-agent-to-hub for that flow, then come back here for the lane itself.

Distribution model (the mental picture)

freeze.py (PyInstaller, native per-OS, no cross-compile)
   └─ email-agent-<platform>[.exe]   ← one-file binary, boots a FastAPI REST sidecar
        └─ POST /publish  →  Agent Hub Worker (workers/agent-hub/) ── R2 bucket "gaia-hub"
             • stores each object IMMUTABLY under agents/<id>/<ver>/<file>
             • computes SHA-256 server-side
             • rebuilds index.json (the catalog the website reads)
        download = plain public GET at hub.amd-gaia.ai/agents/<id>/<ver>/<file>
   └─ @amd-gaia/agent-<id> (npm)  ← typed client + fetch CLI + sidecar lifecycle
        • binaries.lock.json maps platform → {filename, sha256, size}; the SHA-256
          is the integrity gate the fetch CLI enforces on download
        • published via npm OIDC trusted publishing (provenance, NO npm token)

The Worker fronts the bucket; CI never touches R2 directly — it POSTs to /publish so uploads are server-checksummed and the catalog is rebuilt atomically. The manifest + README ride along inside the publish.

What a sidecar agent adds (email = reference)

On top of the normal agent package (manifest + code + README + pyproject.toml, per the guide), a sidecar agent adds:

Notes:

• The npm client is ESM-only ("type": "module"). Node consumers use the . entry (fetch + spawn); browser/Electron renderers use ./client (client-only, zero Node built-ins) — landed in #1773, documented by #1776.
• binaries.lock.json ships placeholder hashes until the first real release. While a hash is a placeholder the fetch CLI is fail-loud — a bad binary can never be fetched. For local dev, point the lifecycle helpers at a locally-frozen binary instead of fetchBinary.
• Manifest validation: validate the author manifest with gaia agent test --lint. Do not validate gaia-agent.yaml against workers/agent-hub/schemas/manifest.schema.json — that is the Hub's server-side aggregate schema and requires fields you never hand-write (versions, latest_version, deprecated, security_tier, permissions).
• Platform-name skew (easy bug): the manifest's requirements.platforms uses win-x64; binaries.lock.json + the CI matrix use win32-x64. Same agent, two spellings — don't copy one into the other.

The three version numbers the release checks

The Resolve + validate release version step fails loudly unless all three are identical:

1. the tag (or workflow_dispatch input) — agent-pkg-<id>-v<version> → <version>
2. hub/agents/<id>/npm/package.json → .version
3. hub/agents/<id>/python/gaia-agent.yaml → version

Bump the Python side with gaia agent version patch|minor|major (it rewrites gaia-agent.yaml + pyproject.toml + __init__.py together — bumping from the gaia-agent.yaml value, ignoring whatever the npm package.json currently says), then manually set the npm package.json to that same version — the release tooling checks all three agree. (Heads up: they can already be out of sync — e.g. a package.json ahead of gaia-agent.yaml — so a blind patch bumps the yaml base, not the npm value; the manual npm sync is what actually reconciles them.) Add the matching CHANGELOG.md entry too if the agent keeps one (recommended, not required by publish). binaries.lock.json's agentVersion

• baseUrl are regenerated by CI — don't hand-edit them for a release.

Cutting a release (existing agent)

1. Version-bump PR → main. gaia agent version <bump>, sync the npm package.json, add the CHANGELOG entry, merge to main (the workflow asserts the release commit is a main ancestor — publishing is allowed only from main).
2. Pre-flight in hub/agents/<id>/npm/: npm ci && npm run build && npm test, and npm pack --dry-run to confirm README.md ships (and CHANGELOG.md, if you keep one).
3. Tag from main (or workflow_dispatch with the version):

   git tag agent-pkg-<id>-v<version> && git push origin --tags

   Namespace is agent-pkg-<id>-* (NOT v*) — it deliberately does not fire the core publish.yml.
4. Build stage freezes on 4 platforms — win32-x64, darwin-arm64, linux-x64 required; darwin-x64 (Intel) best-effort — smoke-tests each, hashes it. (The smoke test proves the binary boots and the REST route answers; with no Lemonade in CI it does not exercise real LLM triage — a 502/timeout passes.)
5. Approve the gate. The publish job pauses on the agent-publish environment until a maintainer approves; the publish token isn't readable until then.
6. Publish stage (atomic): POST every binary to /publish → regenerate binaries.lock.json with the real hashes → fetch-verify every published object against the lock → npm publish via OIDC (provenance) → trigger deploy_website.yml so the new catalog entry appears.

Monitor with gh run watch. npm publish skips if that exact version already exists; /publish is a verified 409 no-op for identical bytes.