Found while adding tests/ttyd-isolation.nix in #650.
Symptom. Declaring a session on the NixOS module with the always-available "shell" pseudo-agent fails eval, before anything boots:
services.agent-box.users.agent: session "main" uses agent "shell", which is
not in services.agent-box.installAgents.
Smallest reproduction — this is the module's OWN documented example for users.<name>.sessions, from the option description (scratch = { agent = "shell"; }):
services.agent-box.users.agent = {
web.passwordHashFile = "/var/lib/agent-box-web/password-hash";
sessions.main.agent = "shell";
};Why. The assertion compares the session's agent against cfg.installAgents:
assertion = builtins.elem (if s.agent != null then s.agent else cfg.agent) cfg.installAgents;
but installAgents is listOf (enum supportedAgents) and supportedAgents = [ "claude" "codex" ], so it can never contain "shell". The module is explicit a few lines above that "shell" is the pseudo-agent that is "always available (nothing to install), so it is appended, never filtered" — the assertion is the one place that does not append it. The runtime path is fine: agent-box-session add <n> --harness shell works, because AGENT_BOX_AGENTS comes from sessionKinds cfg.installAgents, which does append it. So only the DECLARATIVE spelling is broken, which is also the one the docs show.
The native backend has no such gap: bin/agentbox builds the same list as self.spec.agents + ["shell"].
Where the fix goes. modules/agent-box.nix.in, that assertion, comparing against sessionKinds cfg.installAgents instead of cfg.installAgents — the helper that already exists for exactly this and is used two places above. Worth a regression check in the same change: checkout-options is the pattern to copy (it reads config.assertions rather than forcing toplevel, so a failure names WHICH assertion fired, and it asserts the ACCEPTING cases too — here, that agent = "shell" evaluates and that a genuinely unknown agent is still refused).
Workaround meanwhile, which is what #650's VM test does: declare no session and create it at runtime with agent-box-session add <name> --harness shell.
Found while adding
tests/ttyd-isolation.nixin #650.Symptom. Declaring a session on the NixOS module with the always-available
"shell"pseudo-agent fails eval, before anything boots:Smallest reproduction — this is the module's OWN documented example for
users.<name>.sessions, from the option description (scratch = { agent = "shell"; }):Why. The assertion compares the session's agent against
cfg.installAgents:but
installAgentsislistOf (enum supportedAgents)andsupportedAgents = [ "claude" "codex" ], so it can never contain"shell". The module is explicit a few lines above that"shell"is the pseudo-agent that is "always available (nothing to install), so it is appended, never filtered" — the assertion is the one place that does not append it. The runtime path is fine:agent-box-session add <n> --harness shellworks, becauseAGENT_BOX_AGENTScomes fromsessionKinds cfg.installAgents, which does append it. So only the DECLARATIVE spelling is broken, which is also the one the docs show.The native backend has no such gap:
bin/agentboxbuilds the same list asself.spec.agents + ["shell"].Where the fix goes.
modules/agent-box.nix.in, that assertion, comparing againstsessionKinds cfg.installAgentsinstead ofcfg.installAgents— the helper that already exists for exactly this and is used two places above. Worth a regression check in the same change:checkout-optionsis the pattern to copy (it readsconfig.assertionsrather than forcingtoplevel, so a failure names WHICH assertion fired, and it asserts the ACCEPTING cases too — here, thatagent = "shell"evaluates and that a genuinely unknown agent is still refused).Workaround meanwhile, which is what #650's VM test does: declare no session and create it at runtime with
agent-box-session add <name> --harness shell.