feat(server): resolve agent-switch slash commands in RunSession

[trungutt]

Host applications driving the runtime over HTTP had no way to trigger a mid-session agent switch: only the interactive CLI/TUI runners resolved slash commands (via PrepareUserMessage) before appending them to the session. Anyone else — REST clients, Electron hosts, custom orchestrators — could only invoke the target agent via the POST /api/sessions/:id/agent/:agent/:agent_name two-segment route, whose semantics only actually take effect on the first turn of a session (the cached runtime silently ignores it on turn 2+).

This PR closes that gap on the HTTP side. SessionManager.RunSession now runs each incoming user message through LookupCommand / ResolveCommand before appending, mirroring what the CLI already does:

POST /api/sessions/:id/agent/root
body: {"messages":[{"role":"user","content":"/plan design a login flow"}]}
         │
         ▼
    RunSession
         │
         ▼
    applyAgentSwitchCommands
         │
         ├─ LookupCommand("/plan design a login flow")  →  {Agent: "planner"}, rest: "design a login flow"
         ├─ current agent is "root", target is "planner" ➜ SetCurrentAgent("planner")
         └─ replace message content with "design a login flow"
         │
         ▼
    session stores clean history:
      user: "design a login flow"       ◄── no routing prefix leaks in
    runtime runs turn as `planner`

Scope is intentionally narrow: only commands whose Agent field is set are resolved here. Instruction-expansion commands (those declaring an Instruction) pass through unchanged, so an existing caller that happens to send text starting with / is not silently reinterpreted server-side. The blast radius of the change is limited to configs that already declared commands.<x>.agent: <name>, which today are the tightly-controlled agent-switching commands.

Idempotence is a design choice: when the target agent is already current, SetCurrentAgent is skipped. That lets host applications re-assert the desired agent on every turn (e.g. by always prefixing the outgoing message with /plan or /build depending on a UI toggle) without paying for a no-op switch or tracking per-session applied state client-side.

[docker-agent]

Assessment: 🟢 APPROVE

The implementation is clean and correct. applyAgentSwitchCommands correctly mirrors what the CLI's PrepareUserMessage does:

• Two-pass resolution is sound: all LookupCommand / ResolveCommand calls happen against the pre-batch agent before any SetCurrentAgent call, so every message in a multi-message batch is interpreted against the session's starting agent — not against whatever an earlier message switched to.
• Rollback on error is correct: originalAgent is captured before any mutations; if SetCurrentAgent fails mid-batch, the runtime is restored, and the WARN log on rollback failure provides observability without crashing.
• Message content is mutated only after a successful switch: the messages[s.idx].Content = s.content line executes after SetCurrentAgent succeeds (or is skipped as a no-op), so history is never partially rewritten on failure.
• Scope is intentionally narrow: only commands with Agent set are resolved; instruction-expansion commands pass through unchanged, preserving backward compatibility for existing HTTP callers.
• Test suite is thorough: all critical paths are covered — happy path, idempotent re-assertion, instruction-only commands, unknown commands, non-user roles, error propagation, two-pass lookup independence, and mid-batch rollback.

[docker-agent]

Assessment: 🟢 APPROVE

The two-pass design is sound: all LookupCommand calls happen before any SetCurrentAgent call, correctly scoping each lookup to the pre-batch agent. Rollback on failure and the idempotent skip of same-agent switches are both handled correctly. One low-severity logging accuracy issue was found (inline).

[docker-agent]

[low] stuck_on log field names the attempted target, not the agent the runtime is actually on

When both SetCurrentAgent(s.target) and the rollback SetCurrentAgent(originalAgent) fail, the warning log records "stuck_on", s.target. But s.target is the agent the code tried to switch to — and that call failed, so the runtime almost certainly did not move to s.target. The session is more likely stuck on whatever agent it held before the attempt (could be a prior iteration's result or the original), not the one named in the log. An operator reading the warning to diagnose a stuck session would be misled into looking at the wrong agent.

A one-line fix is to query the runtime's actual current state:

Suggested change

	"original_agent", originalAgent, "stuck_on", s.target, "err", rbErr)
	"original_agent", originalAgent, "stuck_on", rt.CurrentAgentName(ctx), "err", rbErr)

Confidence	Score
🟢 strong	100/100

[docker-agent]

Assessment: 🟢 APPROVE

The new applyAgentSwitchCommands function is well-structured with a clear two-pass design that correctly separates lookup from apply. The idempotence check and rollback logic are present and tested. Two minor low-severity observations are noted inline on newly introduced code.

[docker-agent]

[low] stuck_on log field names the wrong agent when rollback also fails

When SetCurrentAgent(ctx, s.target) fails on line 1567, the runtime was never placed on s.target — the call errored out. If a prior iteration in the same batch had already successfully switched to an intermediate agent T_prev, the runtime is currently on T_prev at the point the rollback attempt is made. If the rollback (SetCurrentAgent(ctx, originalAgent)) also fails, the session is stuck on T_prev — but the log records stuck_on: s.target, which is the agent the failed switch was targeting, not the agent the runtime is actually on.

An operator diagnosing a stuck session from this log would search for the wrong agent. The correct value to surface is the runtime's actual current agent at the time of rollback failure, i.e. the result of a rt.CurrentAgentName(ctx) call at that point.

This only manifests when a batch contains multiple agent-switch commands and both the Nth switch and the rollback fail — an uncommon but valid scenario with multi-message batches.

Suggested change

	"original_agent", originalAgent, "stuck_on", s.target, "err", rbErr)
	slog.WarnContext(ctx, "failed to restore agent after switch error; session may be on wrong agent",
	"original_agent", originalAgent, "stuck_on", rt.CurrentAgentName(ctx), "err", rbErr)

Confidence	Score
🟢 strong	97/100

[docker-agent]

[low] Partial message content mutation if a multi-message batch switch fails mid-way

The second-pass loop rewrites messages[s.idx].Content = s.content immediately after each successful SetCurrentAgent, before the loop finishes. If the loop contains multiple switch entries (a batch of messages each starting with a different slash command) and a later entry's SetCurrentAgent fails, the earlier messages will already have had their slash-command prefix stripped while the later ones retain it. The messages slice is passed by reference, so the caller sees a partially-rewritten slice.

In the current RunSession call-site, this is harmless — the caller discards the slice on error (returns nil, err) and never appends anything to the session. But if retry logic is ever added that re-uses the same messages slice, it will encounter inconsistently-modified content (some prefixes stripped, others intact) with no indication that a partial mutation occurred.

A defensive fix is to stage the content rewrites and apply them only after all SetCurrentAgent calls in the loop have succeeded:

Suggested change

	messages[s.idx].Content = s.content
	for _, s := range switches {
	if s.target != rt.CurrentAgentName(ctx) {
	if err := rt.SetCurrentAgent(ctx, s.target); err != nil {
	if rbErr := rt.SetCurrentAgent(ctx, originalAgent); rbErr != nil {
	slog.WarnContext(ctx, "failed to restore agent after switch error; session may be on wrong agent",
	"original_agent", originalAgent, "stuck_on", s.target, "err", rbErr)
	}
	return fmt.Errorf("switch agent to %q: %w", s.target, err)
	}
	}
	}
	for _, s := range switches {
	messages[s.idx].Content = s.content
	}

Confidence	Score
🟡 moderate	70/100