Add a profile/agent concept

[lionello]

Right now, the language in agent-box muddies the terms "agent" and "harness", ie. claude, codex, opencode, … In essence, those are harnesses. The new connections UI for auth (cf. #207 etc.) authenticate a harness.

An agent is like a concrete worker, using a harness, but with a specific model, an optional prompt, perhaps thinking mode, external creds (env), …

We can learn from raphaeltm/simple-agent-manager "profile" concept (without blindly copying all the knobs it has!)

In particular, we need to pick an Agent profile to start a session. A standing webhook needs an Agent profile to hand work off to.

Make sure the docs and code are consistent in their use of language.

[defangdevs]

Dug through the current code to ground this rather than propose in the abstract.

Terminology as it stands today

--agent claude|codex|shell (session-cli.sh) really selects what #321 calls the harness — the CLI program. A few internal comments already say "harness" (agent-box.nix, session-cli.sh, supervisor.sh), but every user-facing surface (the flag name, agent-box-session, README's "each session is one agent") calls it "agent". Renaming the public --agent flag / agent-box-session itself is a big breaking sweep across code, docs, tests, and golden payloads, and "agent-box" as a product name is not up for renaming. So I'd scope the terminology fix to: keep --agent as the harness selector (retitle its help text/docs to say "harness"), and reserve "Agent" / "Agent profile" going forward for the new concept below — not attempt a global word-swap.

Agent profile — concrete shape

A profile = { harness, model?, prompt?, thinking?, env }. Proposed surface, modeled on the existing agent-box-session env pattern:

• Storage: ~/.config/agent-box/agents/<name>.env (same KEY=VALUE, #-comment format already used for ~/.config/agent-box/env; HARNESS=, MODEL=, PROMPT=, THINKING= reserved keys, anything else merged into the session's env).
• CLI: agent-box-agent ls|set|show|rm (mirrors agent-box-session env).
• agent-box-session add [NAME] --profile PROFILE resolves harness/model/prompt/env from the profile; explicit --agent/--prompt/-- EXTRA_ARGS on the command line still win, same override order as env-file vs NixOS option elsewhere in this codebase.

Where it plugs the actual gap

webhook-spawn.sh is explicit about this hole today — render_launch's comment: "The agent is never chosen here — the spawn calls agent-box-session add with no --agent — so the box default is what a match really starts." The only existing override is AGENT_BOX_HOOK_SESSION_ARGS (services.agent-box.webhook.hookSessionArgs, added for #290/#292), which is just a JSON array of extra CLI args (e.g. `["--model","sonnet"]") — it can't pick a harness or carry creds. That's exactly the gap #321 names: "a standing webhook needs an Agent profile to hand work off to."

Proposal: agent-box-webhook subscribe ... --deliver-to subagent --profile NAME stores the profile name on the watch, and the spawn path passes --profile NAME to agent-box-session add instead of (or layered under) AGENT_BOX_HOOK_SESSION_ARGS.

A real blocker: creds

"External creds (env)" in a profile assumes per-session env isolation. It doesn't exist: env today is per-user (~/.config/agent-box/env), and per the "sessions are not isolated" finding, sibling sessions on the same account already read each other's /proc/*/environ — there's no boundary there at all yet. That's #135 (open: "A way to have volatile / non-persisted per session env"). Shipping a profile's env block as real per-session secrets means #135 needs to land first, or the profile's env leaks to every sibling session on that account, not just the ones that opted into that profile.

Recommendation: ship {harness, model, prompt, thinking} as v1 (covers the webhook hand-off case, which is the concrete pain point), track the env/creds field as blocked on #135, and land the harness/profile terminology split in docs as a small standalone PR since it's low-risk and unblocks writing the rest of this consistently.

Happy to open the v1 PR (profile storage + CLI + --profile on session add and webhook subscribe) once this shape looks right — didn't want to land a rename/new-CLI-surface blind on infra the box runs itself on without a sanity check first.

[defangdevs]

Triage notes from code, before any implementation.

Current state

• "Agent" already means "harness" everywhere. services.agent-box.agent sets the default harness. installAgents lists allowed harnesses. sessionOpts.agent picks the harness per session. (modules/agent-box.nix:3745-3749, :2438-2448)
• The session schema has no model field and no thinking field. Model choice today is a raw string inside extraArgs, e.g. ["--model","sonnet"].
• The webhook dispatcher never picks a harness. It calls agent-box-session add with no --agent. The box default harness always runs. (modules/src/webhook-spawn.sh, comment near line 104: "the box default is what a match really starts")
• No "profile" concept exists in code, Nix options, or docs. This issue is the first mention.
• The issue names codex and opencode as harnesses. Opencode is not supported yet: Support for OpenCode #184 asked for it and was closed not-planned; Add opencode support #80 is open and is the real tracking issue.
• Build interactive auth flow for Claude #207 (closed) built harness auth ("Connections" UI) only. It does not touch model, prompt, or profile.

Proposed shape, split into small steps

1. Terminology pass only. Fix doc/comment text that says "agent" but means "harness." Keep Nix option names as-is for now (avoid a breaking rename); write the mapping down once, e.g. in the wiki.
2. Add "Agent profile" as a self-serve, runtime concept — not a new services.agent-box.* Nix option. Per the precedent in feat(webhook): let a per-user env override hookSessionArgs, no rebuild #291, this is per-user preference data, so store it under ~/.config/agent-box/ and manage it with a CLI, not a rebuild. A profile bundles: harness, model, optional prompt append, optional thinking-mode flag, optional env overlay.
3. Teach agent-box-session add a --profile NAME flag that resolves to harness+model+prompt+env. Keep --agent/--prompt as an override on top.
4. Let a standing webhook watch name a profile to hand off to, instead of always using the box default harness. This is the "standing webhook needs an Agent profile" half of the issue.
5. Later: a profile picker in the settings UI, next to the harness-auth "Connections" section from Build interactive auth flow for Claude #207.

Open question

Should a profile carry its own credentials (its own env overlay), or should credentials stay at the user level, with a profile only picking harness+model+prompt+thinking? Own credentials per profile is more powerful, but it is new secret-handling surface.

Want me to open steps 2-5 as separate tracking issues once the shape looks right, or go ahead now with step 1 (the low-risk terminology pass)?

[defangdevs]

v1 is up as #337 — the shape from the triage comment above, with two changes to what I proposed there, both deliberate:

"profile", not "agent", on the code surfaces. agent-box-profile, --profile, ~/.config/agent-box/profiles/<name>.env. --agent keeps meaning the harness, so nothing breaks and no word does two jobs at the same time. The docs say "agent profile" and reserve "Agent" for the concept, per this issue; a breaking --agent→--harness rename can still happen later on top of a surface that is already unambiguous.

The env overlay ships, rather than waiting on #135. A profile's non-reserved keys are exported into sessions started with it, at every spawn, from the profile name recorded in the registry — so a rotated token applies on the next restart. It is documented everywhere it appears (README, --help, code) as convenience and NOT isolation: a sibling session of the same user reads it out of /proc/<pid>/environ, and the VM test asserts it that way on purpose. Per-profile creds as a real boundary is still #135's job.

Also settled while building it:

• SYSTEM_PROMPT, not PROMPT, for the appended system prompt — agent-box-session --prompt is the kickoff task, and one word cannot be both.
• EFFORT covers the "thinking mode" bullet: claude --effort LEVEL, codex -c model_reasoning_effort=LEVEL. codex has no --append-system-prompt equivalent, so a profile that sets one for codex says so instead of dropping it silently.
• The harness-specific mapping lives in exactly one place (agent-box-profile launch NAME [HARNESS]), and --agent is passed into it, so a codex profile started with --agent shell does not get handed codex's flags.
• Arguments resolve at CREATE time, env resolves at every SPAWN. A running session therefore keeps the arguments it started with (the rule hookSessionArgs already states) while a rotated secret still reaches it on restart.

Step 4 landed only in its box-wide form: AGENT_BOX_HOOK_PROFILE in the env store picks the worker for every later dispatched hook-* session. A per-watch --profile cannot be honest yet — the watch record lives in local-webhook and the spawn command receives only LOCAL_WEBHOOK_SPAWN_{SOURCE,KEY,EVENT,TOPIC,NOTE,COUNT}, so it needs an upstream field in defangdevs/local-channels first. Same upstream dependency #333 has. Step 5 (a picker on the settings page) is untouched; the page's watch panel does now name the profile, because it prints the spawn wrapper's own --preamble.

Step 1 (the terminology pass over the rest of the docs) is not in the PR either — #337 makes the harness/profile split correct everywhere it touches, and sweeping the remaining "agent means harness" prose is a separate low-risk diff, better reviewed on its own.