Upgrading from warp¶
The product was called warp. It is called Humagen now: the Go module is
github.com/urmzd/humagen, the command is humagen, and every setting,
file and name a person types starts with humagen or HUMAGEN_.
Nothing an existing deployment holds needs to change on the day it upgrades. Every name people typed before still works, and the server prints a note at start for each one it read, naming the new one. Every name that stored data or a running deployment depends on is kept as it was. This page lists both, and what an operator does, when they choose to, to move to the new names.
Old names are read for good unless a later release says otherwise in its breaking changes, with a release of notice. Kept names do not change.
What changes¶
| What | Was | Is |
|---|---|---|
| Repository | github.com/urmzd/warp |
github.com/urmzd/humagen (GitHub redirects the old address) |
| Go module and root package | github.com/urmzd/warp, warp.Main |
github.com/urmzd/humagen, humagen.Main |
| Command | warp, cmd/warp |
humagen, cmd/humagen |
| Settings | WARP_* |
HUMAGEN_* (settings) |
| Config file | ~/.config/warp/warp.yaml, $WARP_HOME/warp.yaml |
~/.config/humagen/humagen.yaml, $HUMAGEN_HOME/humagen.yaml (config file) |
| Spec | api_version: warp/v1, surfaces.slack.warp_client, warp_token |
humagen/v1, humagen_client, humagen_token (spec) |
| Machine scopes | warp:runs:read |
humagen:runs:read (sign-in) |
| Default groups | warp-admins, warp-managers, warp-operators, warp-viewers |
humagen-admins, humagen-managers, humagen-operators, humagen-viewers |
| Helm chart | deploy/helm/warp, chart warp |
deploy/helm/humagen, chart humagen (Kubernetes) |
| Image | warp:local, /usr/local/bin/warp, user warp |
humagen:local, /usr/local/bin/humagen (with a warp link), user humagen, same uid (image) |
| Compose settings | WARP_IMAGE, WARP_BIND, WARP_PORT, WARP_EXTRA_ARGS, WARP_S3_BUCKET |
HUMAGEN_*, each falling back to its WARP_ name (compose) |
Where deploy writes a compose project |
.warp/compose |
.humagen/compose, or .warp/compose when it is there |
| GitHub review format | warp.github.review.v1 |
humagen.github.review.v1; both are rendered (GitHub) |
| Slack app name | Warp, Ask Warp | Humagen, Ask Humagen, once the manifest is applied again (Slack) |
| Release notes sender | warp |
humagen; both are shown as Humagen |
| Session cookies | warp_session, warp_login |
humagen_session, humagen_login. Sessions are kept in memory, so a restart signs everyone out anyway |
| npm workspace scope | @warp/* |
@humagen/* (private packages, nothing published) |
| Console sidebar setting | warp.sidebar in the browser |
humagen.sidebar, moved once on the first visit |
Settings¶
The server copies each setting it reads that is set only under its old name to its new one, at start, before any command runs, and says so:
The rule is the same everywhere: when both names are set and not blank, the
new one wins, and the note says HUMAGEN_X and WARP_X differ; using HUMAGEN_X.
A blank value counts as unset. An old name is never unset, and a note names
variables, never their values.
Only the variables the server reads are copied: the settings
(internal/legacy lists them: HUMAGEN_HOME, HUMAGEN_POSTGRES_URL,
HUMAGEN_OIDC_*, HUMAGEN_SLACK_*, HUMAGEN_GITHUB_* and the rest), with a
note for each; a people's-credential variable (WARP_PERSON_*) or a variable
a -secret-refs or secret_env grant names is noted when only its old name is
set. Other
programs export WARP_ variables of their own (the Warp terminal sets
WARP_IS_LOCAL_SHELL_SESSION), and those are left alone.
References read either name. A reference stored before the upgrade, in a
client record, a person's credential or a spec (env:WARP_SLACK_TOKEN_DOCS),
reads HUMAGEN_SLACK_TOKEN_DOCS when that is set and WARP_SLACK_TOKEN_DOCS
otherwise. So an operator renames the variable in the environment, and leaves
the references as they are: they are data the workspace stored. The same holds
where names are compared: a -secret-refs or secret_env grant, and a
person_refs start, name one variable whichever prefix each was written with.
env:WARP_PERSON_{subject}_ and env:HUMAGEN_PERSON_{subject}_ are one start,
so they cannot be given to two workspaces. Do not rename a keychain: or
op:// start: those name places outside Humagen, and the references stored
under them would stop being their people's.
The sign-in secret is the server's own under both names: no client or person
may reference HUMAGEN_OIDC* or WARP_OIDC*.
The Slack app reads its own settings the same way (WARP_TENANT, WARP_URL,
WARP_TOKEN, WARP_OIDC_* and the rest), and logs a note for each at start.
The server passes the Slack app it launches its settings under both names, so
an app directory from before the rename still starts. The console's dev
server reads HUMAGEN_API, else WARP_API with a warning.
The test settings (HUMAGEN_POSTGRES_TEST_URL, HUMAGEN_TEST_S3_*) fall back
too. HUMAGEN_TEST_COMMAND, HUMAGEN_SERVER_TEST and deploy/helm/check.sh's
HUMAGEN override do not: they are development tools.
Config file¶
start, setup, config and deploy look for the spec in this order:
- With
HUMAGEN_HOME(orWARP_HOME) set:humagen.yamlthere, elsewarp.yamlthere. Nothing outside that directory. - Without it:
~/.config/humagen/humagen.yaml, else~/.config/warp/warp.yaml(the user config directory of the platform).
An old file is read where it is, with a note. It is never moved, so the
release before the rename still finds it. setup writes back to the file it
read, in the language that file was in, so an older binary can still read it.
Both files present is an error: keep one. To move, mv the file and change
its api_version.
Spec¶
api_version: warp/v1 is read, with a note, and so are
surfaces.slack.warp_client and warp_token, which become humagen_client
and humagen_token. A file that sets both names of one field is refused.
humagen config print writes the new names.
The shipped compose specs (deploy/compose/config/warp.yaml and
deploy/compose/dev/warp.yaml) keep their names and their contents, since
people edit them in place and an image from before the rename must still read
them. Their display_name is still Warp, which names the console and the Slack
app; set it to Humagen in your copy when you want the new name shown.
Sign-in¶
Tokens whose scopes use the old prefix (warp:runs:read) keep their
permissions. Define the humagen: scopes at the identity provider before
changing a machine client's scopes in the spec; humagen config check notes
the old prefix and says the same.
With no policy file, the default groups grant their roles under both names:
humagen-admins and warp-admins are both admin. A -*-group flag set for a
role, or a policy file, drops the old name for that role, as it drops the
default. Under OIDC the server notes the old groups it grants. Name your
groups in auth.groups or a policy file to stop relying on either default.
Kubernetes¶
A release the warp chart installed names its Deployment, Service, ConfigMap
and volume claim warp (or <release>-warp), with the selector
app.kubernetes.io/name: warp. The humagen chart would name them for itself
and start a second, empty server beside them, so it refuses to upgrade such a
release: set nameOverride: warp and it keeps every name and the volume.
helm upgrade warp deploy/helm/humagen -n warp --reuse-values \
--set nameOverride=warp --set image.tag=<0.21.0 or later> --wait --atomic
--reuse-values keeps the old image tag, which cannot read the spec this
chart writes, so name the new one; --atomic rolls back if the pod does not
come up. The container keeps the name warp too, so patches and
kubectl logs -c warp keep working.
For a memory store, set system.spec.stores.kind: memory and
system.spec.stores.postgres: null in the chart values. The chart omits null
store entries from the generated spec, including nulls retained by Helm 4's
--reuse-values. Non-null blocks for an inactive backend are still refused;
a selected Postgres backend still needs its database reference.
humagen deploy does this itself, on every deploy that applies: it asks helm
whether the release was installed by the warp chart, or was given
nameOverride: warp, and keeps the name. humagen deploy -o applies nothing
and asks nothing, so add nameOverride: warp to the kubernetes block's
values when writing for such a release; the chart refuses it otherwise. The guard reads the cluster, so helm template renders without
it.
The image must be 0.21.0 or later, the first release under the new name: the
chart writes api_version: humagen/v1, which images from before the rename
refuse. The chart's default tag is 0.21.0, and the chart, and humagen deploy,
refuse a release tag older than that rather than roll an image that would
crash. A tag that is not a release version (a commit, latest) is not
checked: build it from this release or later. The
chart's defaults reference HUMAGEN_OIDC_CLIENT_SECRET and
HUMAGEN_POSTGRES_URL; a Secret that holds WARP_OIDC_CLIENT_SECRET and
WARP_POSTGRES_URL keeps working with the new image. The paths in the pod
(/var/lib/warp, /etc/warp) are kept.
Flux¶
Flux uninstalls and reinstalls a release whose chart changes name, unless the
HelmRelease says otherwise. That takes the server down, deletes the
Deployment and Service, and leaves the guard above nothing to check. The
example's HelmRelease therefore sets
spec.upgrade.chartNameChangeStrategy: InPlaceUpdate, and its values set
nameOverride: warp. A cluster that copied deploy/flux/app changes four
things in its copy, in one commit:
spec.chart.spec.chart: ./deploy/helm/humagenspec.upgrade.chartNameChangeStrategy: InPlaceUpdatenameOverride: warpin its valuesimage.tagin its values: 0.21.0 or later (a copy of the old example pins0.9.0, which cannot read the spec; the chart refuses it)
and points its GitRepository's url at https://github.com/urmzd/humagen.
Until the chart path changes, the chart fetch fails and the running release
stays as it is. The namespace, the HelmRelease, the GitRepository, the
Kustomization and the warp-env Secret keep their names: the example
Kustomization prunes, so renaming any of them would delete it.
chartNameChangeStrategy needs helm-controller 1.6.0 or later, which first
ships with Flux 2.9 (Flux 2.7 ships 1.4.0, and 2.8 ships 1.5.0). An older
controller drops the field and uninstalls and reinstalls the release when the
chart's name changes. On Flux before 2.9, upgrade Flux first. Until then, keep
the cluster on the warp chart: pin the GitRepository to the tag v0.20.2
(ref: {tag: v0.20.2}) and leave the chart path ./deploy/helm/warp, so
nothing changes until Flux can upgrade the release in place.
Compose¶
deploy/compose keeps its project name (warp), service, volumes
(warp_warp-data, warp_postgres-data) and its Postgres user, database and
default password, so an existing stack keeps its data. A .env with WARP_
names keeps working: each HUMAGEN_ variable in compose.yaml falls back to
its WARP_ name, and the stack sets the database URL under both names, so a
rollback to an image from before the rename still finds it. The default image
tag is humagen:local, built on the next docker compose up --build.
A compose project humagen deploy wrote keeps its identity too, and is
written again to .warp/compose when an earlier deploy wrote there. Its file
passes each variable a spec names from the shell under either name. Its
compose.image must be 0.21.0 or later: deploy refuses an older release tag,
whose image cannot read the spec it writes, and does not check a tag that is
not a release version.
Image¶
The image runs /usr/local/bin/humagen. /usr/local/bin/warp links to it,
for custom entrypoints and docker exec ... warp, and running it by that name
prints a note. The user is humagen with the same uid and gid, 10001, so a
volume's files stay its own. /var/lib/warp (the home, the cache and the
volume), /etc/warp (the spec) and /usr/share/warp/web (the console) are
kept, since volumes and specs bind them.
Nothing publishes an image yet. A workflow that starts to should push each tag
under both ghcr.io/urmzd/warp and ghcr.io/urmzd/humagen for one release,
since GitHub's container registry does not follow a repository rename.
Slack¶
An installed Slack app keeps its name until its manifest is applied again:
humagen slack manifest, then App Manifest in the app's settings (or
slack manifest sync for the sandbox). Nothing depends on the name: the
callback ids, the commands, the scopes and the events are unchanged. A
deployment that wants to stay "Warp" sets app_name or display_name in its
spec, or SLACK_BRANDING. The stream journal stays in
$XDG_STATE_HOME/warp-slack/, and the warp.connections view callback stays,
since open modals carry it.
GitHub¶
Agents whose instructions ask for warp.github.review.v1 keep getting
reviews; new examples use humagen.github.review.v1. A /fix grant issued
before the upgrade still verifies: its domain, warp.github.mutation.v1, is
kept. The GitHub App's login is configuration: if the App is renamed, set
HUMAGEN_GITHUB_LOGIN to the new login and list the old one in
HUMAGEN_GITHUB_BOTS.
Go¶
Programs that import the module change their import path to
github.com/urmzd/humagen and warp.Main to humagen.Main. Versions tagged
before the rename keep resolving under the old path through the module proxy
and GitHub's redirect; the old path's @latest fails with
module declares its path as: github.com/urmzd/humagen, which names the new
one. There is no deprecation release on the old path.
The event union and fiber's fold¶
The release that folds fiber into this repository also moves every event onto one envelope with a typed body (API contract). Upgrade like this:
- Stop the old process first. Stop every process of the old release before the new one starts on the same database: an older release keeps its stores in memory and must not run beside a newer one. The agent move below runs once at start behind a marker.
- Runs in flight fail terminally. A run recorded under the old activity
names (
fiber.turn,fiber.turn.agent,fiber.turn.resume) ends as failed with a reason instead of replaying a turn the new code cannot pin. Let runs finish, or start them again after the upgrade. - Agents are converted. The first start moves
fiber_agentsandfiber_agent_revisionsinto the agent store (pkg/agents): revision N becomes version N.0.0, keeping who wrote it and when. An agent whose name breaks saige's rule is disabled: left out, logged at start, and kept in the move's report (legacy.AgentConversionOf). A platform agent that cannot be moved fails the start. - The bus is new. Events go to new bus tables (
fiber_events,fiber_event_runs); rows of the old bus age out within 24 hours. A run's record and its events in the ledger are read as before. - Webhook bodies are version 2. fiber's outbound webhook connector,
which Humagen does not configure itself, now posts the envelope with
inline
dataandFiber-Event-Version: 2. An endpoint's old kind selector (lifecycle.completed) is read as its type; one it does not know is a configuration error. - The old SSE topic is translated.
GET /api/events?topic=still takesagent,agent:<name>andagent:<name>:<run>, read as that agent's or run's events throughinternal/legacy, andGET /api/journal?kind=is read as a type. Both are deprecated; a client regenerated fromapi/openapi.yamluseschannel,typeandrun. - A program on the
humagenpackage imports fiber fromgithub.com/urmzd/saige/flow/...(spec).
Kept names¶
| Name | Why it stays |
|---|---|
Tag meta keys warp.thread, warp.prev, warp.ask, warp.picked, warp.project, warp.channel, warp.message, warp.within, warp.sources, warp.client, warp.deliver, warp.call_input, the call edges warp.root, warp.parent, warp.depth, warp.mode, warp.lease, the housekeeping keys warp.hook, warp.for, warp.keeps_notes, warp.place.project, warp.place.thread, and the private _warp.sources, _warp.skills, _warp.routed |
Stored in run records, schedules and anchor's ledger. Reading two names would mean deleting both at every point that strips them, or a caller could smuggle an old key past admission |
Postgres table warp_state and lock class 0x77617270 |
An older binary would create an empty table, and an older and a newer process on one schema must still exclude each other |
Compatibility agent handles warp-writer, warp-analyst, warp-builder |
Existing registry revisions, runs, schedules, allow-lists, project lists and mentions remain readable. New choices use humagen-writer, humagen-analyst, humagen-builder |
/fix grant domain warp.github.mutation.v1 |
Grants in flight keep verifying |
Image paths /var/lib/warp, /etc/warp, /usr/share/warp/web, uid 10001 |
Volumes and specs bind them |
Workspace os.UserCacheDir()/warp/workspace |
Attachments and files stored records point at |
Slack journal warp-slack/ and view callback warp.connections |
The next start reads the journal; open modals carry the callback |
References humagen deploy carries into a target, WARP_REF_n |
A Secret written before the rename holds them, and a rollback reads them |
Compose project, service, volumes, Postgres user and database warp |
Volumes are named for the project, and Postgres creates its user only once |
System metadata.name default and humagen deploy's namespace default, warp |
They name existing compose projects, Helm releases and their <release>-env Secrets |
Flux namespace, HelmRelease, GitRepository, Kustomization and warp-env Secret |
The example prunes |
A warp chart release's resource names (nameOverride: warp) |
Its volume and selector |
Fiber's Postgres tables fiber_definitions, fiber_definition_retirements, fiber_events, fiber_event_runs, fiber_memberships, fiber_runs, fiber_run_records, fiber_run_queue, fiber_threads, fiber_thread_entries, fiber_knowledge_documents, fiber_knowledge_chunks, fiber_tool_providers, fiber_tool_snapshots, the bus's consumer group tables added later (fiber_event_tenants, fiber_consumers, fiber_dispatch_runs), durable connector delivery state (fiber_sink_state), and session state (fiber_sessions, fiber_session_runs, fiber_session_links, fiber_session_grants, fiber_session_budgets, fiber_session_reservations, fiber_session_totals, fiber_session_usage_ids), with their indexes |
The tables are kept. Fiber now lives in github.com/urmzd/saige/flow, and Humagen's internal/runschema maps the run ledger and queue onto these tables; the stores keep their rows across the move. fiber_knowledge_documents, fiber_knowledge_chunks and fiber_dispatch_runs are no longer created by anything, and an existing database keeps them |
Durable activity names fiber.turn.v2, fiber.turn.agent.v2, fiber.turn.resume.v2, and the v1 names fiber.turn, fiber.turn.agent, fiber.turn.resume |
The durable ledger (formerly anchor's) stores runs under them. A run under a v1 name fails terminally with a reason instead of replaying |
Run record keys fiber.stop, fiber.question., fiber.answer., fiber.child., fiber.usage.a |
A run in flight reads its records back by these names |
internal/legacy/kept_test.go pins every name in this table that code
defines, and fails when a fiber store creates a table not listed here.
Fiber's own earlier names are in renaming.md.
Choices the owner can flip¶
These are the defaults this release takes. Each can change in a later release.
- Built-in agent handles are
humagen-writerandhumagen-analyst, pluscode-reviewer,security-reviewer,architect-reviewerandqa-reviewerfor code reviews in ordinary chat. The builder is now the entry agent,humagen;humagen-builderandwarp-builderread as it. A workspace that already has them keeps them; a new workspace starts withhumagenandapproverand installs the rest (the Core and Review packages) from the agent store. The directory lists these handles. Compatibility definitions remain underwarp-writer,warp-analystandwarp-builder, protected from edits like the new ones and updated to the configured provider and model. They keep the original keys and revision hashes: old runs, schedules, project lists, call grants and client defaults are not re-keyed. New configuration should use the new handles. If an existing custom agent already uses one of them, startup refuses to overwrite it: preserve it under another name before upgrading. An allow-list for an old handle continues to grant only that handle; the rename grants no new access. - Old default groups (
warp-*) keep their roles while the defaults are in force, with a note under OIDC. A later release could stop granting them; an identity provider that holds groups of those names for another product grants roles until then. - Deployment defaults stay
warp: the Systemmetadata.namedefault andhumagen deploy's Kubernetes namespace. A later release could default tohumagenand refuse a spec that leaves them unset. - Image paths stay under
warp(/var/lib/warp,/etc/warp,/usr/share/warp/web), with the cache workspace and the Slack journal. A later release could move them behind links once that is tested on Docker and Kubernetes. - No deprecation release on the old module path.
After this merges: the owner's steps¶
- Rename the repository
urmzd/warptourmzd/humagenin its settings, before merging, so the release's Go publish finds the new path. Never create a newurmzd/warp: the redirect stops working. Point each clone at the new address:git remote set-url origin https://github.com/urmzd/humagen. - Merge, then check from a clean module cache that
go install github.com/urmzd/humagen/cmd/humagen@<the new tag>works. - Apply the Slack manifest again on each installed Slack app
(
humagen slack manifest, then App Manifest in the app's settings). - If the GitHub App is renamed, set
HUMAGEN_GITHUB_LOGINto its new login and add the old one toHUMAGEN_GITHUB_BOTS. - In each Flux cluster, point the
GitRepository'surlathttps://github.com/urmzd/humagen(whether Flux follows GitHub's redirect is not verified), and in a copieddeploy/flux/app, make the four changes under Flux. - Merge the library documentation follow-ups (fiber, anchor, saige, playscape), which link here.
- Capture
showcase/*.pngagain.