diff --git a/docs/2-handbook/swarm/ui.md b/docs/2-handbook/swarm/ui.md index 7700eea22..4d444d3bb 100644 --- a/docs/2-handbook/swarm/ui.md +++ b/docs/2-handbook/swarm/ui.md @@ -34,11 +34,13 @@ system raised it and how long ago. You can't change it from here, and it follows the agent's own list within a few seconds. Type `/` in an agent's message box and a menu lists what that agent accepts: -the swarm's own commands (`/compact`, `/clear-todos`) and the skills the -agent's harness published. Arrow keys move, Tab completes, Esc closes. Skills -are per agent, so two agents can offer different lists. `/clear-todos` marks all -of the agent's todos done without starting a turn, and the terminal shows how -many it cleared. +the swarm's own commands and the skills the agent's harness published. Arrow +keys move, Tab completes, Esc closes. Skills are per agent, so two agents can +offer different lists. The swarm's commands are `/compact`, which compacts the +agent's context after its current turn; `/clear`, which starts its next turn on +a fresh session; and `/clear-todos`, which marks all of the agent's todos done +without starting a turn, the terminal showing how many it cleared. Send each +alone, as it is a command and not a message. Each page, its controls and what they send are in [the swarm UI reference](../../4-implementation/web-ui/swarm-ui.md). diff --git a/docs/4-implementation/swarm/controller.md b/docs/4-implementation/swarm/controller.md index 94a720264..91c8965fc 100644 --- a/docs/4-implementation/swarm/controller.md +++ b/docs/4-implementation/swarm/controller.md @@ -356,8 +356,10 @@ The text holds no secret, so nothing goes through the secret store. **Editing.** `PUT /api/agents//agents-md` takes `{base_revision, diff}`. The diff is a unified diff that names `a/AGENTS.md` and `b/AGENTS.md`, made against the text at `base_revision`. swarm-controller sends it as a request on -the agent's command subject `$SWARM.control.`, as it sends a cancel. The -harness refuses it when the file isn't at `base_revision`. Otherwise it runs +the agent's command subject `$SWARM.control.`, as it sends a cancel. (The same +subject carries `POST /api/agents//new-session`, which the swarm UI sends for +`/clear`: the harness queues a session reset that takes effect at the agent's next +turn, and answers `acted: true`.) The harness refuses it when the file isn't at `base_revision`. Otherwise it runs `git apply --check` and then `git apply` on a copy of the file, and writes the result over the file only when both pass: diff --git a/frontend/packages/swarm-ui/src/agent/terminal/AgentInputForm.tsx b/frontend/packages/swarm-ui/src/agent/terminal/AgentInputForm.tsx index 91be52a60..309d9e9f5 100644 --- a/frontend/packages/swarm-ui/src/agent/terminal/AgentInputForm.tsx +++ b/frontend/packages/swarm-ui/src/agent/terminal/AgentInputForm.tsx @@ -4,6 +4,10 @@ // sees it as an inbox turn from the logged-in user (the controller takes the // sender from the gateway, not from this request). // +// Sending exactly `/clear` is not a message: it POSTs +// `/api/agents/{name}/new-session`, which queues a fresh claude session for the +// agent's next turn (`controlRoute`). +// // While the text is one `/word`, a menu of the agent's commands and skills // opens above the box (`CommandMenu`): the arrow keys move, Tab or Enter take // the selected one into the box, Esc closes it. The list is the agent's own @@ -16,6 +20,7 @@ import { useSubmit } from "../../ui/submit/useSubmit.js"; import { CommandMenu } from "./CommandMenu.js"; import { completion, + controlRoute, enterSends, matchCommands, menuQuery, @@ -47,13 +52,17 @@ export function AgentInputForm({ agentName }: { agentName: string }) { function submit(e: Event) { e.preventDefault(); + const base = `/api/agents/${encodeURIComponent(agentName)}`; + const route = controlRoute(body, commands); void run( () => - fetch(`/api/agents/${encodeURIComponent(agentName)}/input`, { - method: "POST", - headers: { "content-type": "application/json" }, - body: JSON.stringify({ body }), - }), + route + ? fetch(`${base}/${route}`, { method: "POST" }) + : fetch(`${base}/input`, { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ body }), + }), { onDone: () => setBody("") }, ); } diff --git a/frontend/packages/swarm-ui/src/agent/terminal/command-menu.ts b/frontend/packages/swarm-ui/src/agent/terminal/command-menu.ts index 866f05915..16fb9fb96 100644 --- a/frontend/packages/swarm-ui/src/agent/terminal/command-menu.ts +++ b/frontend/packages/swarm-ui/src/agent/terminal/command-menu.ts @@ -92,3 +92,19 @@ export function moveSelection( export function enterSends(text: string, selected: AgentCommand): boolean { return text.trim() === `/${selected.name}`; } + +/** + * The route, under `/api/agents/{name}/`, a sent text stands for when it is one + * of the swarm's own control commands, else `null` for a plain message. Only + * the list the backend served counts: `/clear` is a command there, so an agent + * with a skill of that name (which the backend drops) still sends text. + */ +export function controlRoute( + text: string, + commands: AgentCommand[], +): "new-session" | null { + const isClear = + text.trim() === "/clear" && + commands.some((c) => c.kind === "command" && c.name === "clear"); + return isClear ? "new-session" : null; +} diff --git a/frontend/packages/swarm-ui/test/command-menu.test.mjs b/frontend/packages/swarm-ui/test/command-menu.test.mjs index 577779a2b..83d309147 100644 --- a/frontend/packages/swarm-ui/test/command-menu.test.mjs +++ b/frontend/packages/swarm-ui/test/command-menu.test.mjs @@ -4,6 +4,7 @@ import assert from "node:assert/strict"; import { test } from "node:test"; import { completion, + controlRoute, enterSends, matchCommands, menuQuery, @@ -98,3 +99,17 @@ test("Enter sends once the selected command is already typed in full", () => { assert.equal(enterSends("/comp", cmd("compact")), false); assert.equal(enterSends("/", cmd("compact")), false); }); + +test("exactly /clear, with the backend's command of that name, is a new session", () => { + const list = [cmd("compact"), cmd("clear")]; + assert.equal(controlRoute("/clear", list), "new-session"); + assert.equal(controlRoute("/clear ", list), "new-session"); + assert.equal(controlRoute("/clear it", list), null); + assert.equal(controlRoute("/compact", list), null); + assert.equal(controlRoute("clear", list), null); +}); + +test("without the backend's /clear command, or with a skill of that name, it is text", () => { + assert.equal(controlRoute("/clear", []), null); + assert.equal(controlRoute("/clear", [cmd("clear", "skill")]), null); +}); diff --git a/hive-agent/src/swarm_input.rs b/hive-agent/src/swarm_input.rs index 9bc817a97..489b00487 100644 --- a/hive-agent/src/swarm_input.rs +++ b/hive-agent/src/swarm_input.rs @@ -81,6 +81,13 @@ async fn run_control( let Some(answer) = act( &msg.payload, || crate::web_ui::cancel_turn(&bus, &interrupted, "swarm UI: cancel"), + || { + bus.request_session_reset(); + bus.emit(crate::events::LiveEvent::Note { + text: "operator: session reset queued (/clear) — takes effect at the next turn" + .into(), + }); + }, crate::swarm_agents_md::handle, ) .await @@ -93,12 +100,13 @@ async fn run_control( } } -/// The encoded answer to a command payload: `cancel` runs for a cancel and -/// `apply` for an `AGENTS.md` edit. `None` (logged) when the payload is not a +/// The encoded answer to a command payload: `cancel` runs for a cancel, +/// `new_session` for a session reset and `apply` for an `AGENTS.md` edit. `None` (logged) when the payload is not a /// command, which gets no answer. async fn act( payload: &[u8], cancel: impl FnOnce() -> bool, + new_session: impl FnOnce(), apply: impl FnOnce(swarm_queue_client::agents_md::Apply) -> F, ) -> Option> where @@ -110,6 +118,10 @@ where Ok(AgentControl::Cancel) => { serde_json::to_vec(&swarm_queue_client::AgentControlReply { acted: cancel() }) } + Ok(AgentControl::NewSession) => { + new_session(); + serde_json::to_vec(&swarm_queue_client::AgentControlReply { acted: true }) + } Ok(AgentControl::ApplyAgentsMd(edit)) => serde_json::to_vec(&apply(edit).await), Err(e) => { tracing::warn!(error = %e, "swarm control: undecodable command dropped"); @@ -321,6 +333,7 @@ mod tests { let got = act( br#""cancel""#, || acted, + || panic!("reset the session for a cancel"), |_| async { panic!("applied an edit for a cancel") }, ) .await @@ -341,6 +354,7 @@ mod tests { let got = act( &payload, || panic!("cancelled for an edit"), + || panic!("reset the session for an edit"), |got| async move { assert_eq!(got, edit); ApplyReply::Applied { @@ -364,9 +378,26 @@ mod tests { let got = act( b"pause", || panic!("ran a command that was not one"), + || panic!("ran a command that was not one"), |_| async { panic!("ran a command that was not one") }, ) .await; assert_eq!(got, None); } + + #[tokio::test] + async fn a_new_session_resets_once_and_is_answered_as_acted() { + let resets = std::cell::Cell::new(0); + let got = act( + br#""new_session""#, + || panic!("cancelled for a new session"), + || resets.set(resets.get() + 1), + |_| async { panic!("applied an edit for a new session") }, + ) + .await + .expect("answered"); + let got: AgentControlReply = serde_json::from_slice(&got).expect("a reply"); + assert_eq!(got, AgentControlReply { acted: true }); + assert_eq!(resets.get(), 1); + } } diff --git a/swarm-controller/src/agent_commands.rs b/swarm-controller/src/agent_commands.rs index 12c32b77f..18dfa65c5 100644 --- a/swarm-controller/src/agent_commands.rs +++ b/swarm-controller/src/agent_commands.rs @@ -18,11 +18,15 @@ use crate::routes::AppState; /// The commands the swarm UI offers every agent: the name without the slash, /// and what it does. -const COMMANDS: [(&str, &str); 2] = [ +const COMMANDS: [(&str, &str); 3] = [ ( "compact", "Compact this agent's context after the current turn", ), + ( + "clear", + "Start the next turn on a fresh session, dropping this one's context", + ), ("clear-todos", "Mark all of this agent's todos done"), ]; @@ -164,7 +168,7 @@ mod tests { #[test] fn the_swarms_commands_come_first_and_always() { let list = build(None); - assert_eq!(names(&list), ["compact", "clear-todos"]); + assert_eq!(names(&list), ["compact", "clear", "clear-todos"]); assert!(list.iter().all(|e| e.kind == CommandKind::Command)); } @@ -173,8 +177,11 @@ mod tests { let list = build(Some(Skills { skills: vec![skill("zeta", "z"), skill("alpha", "a")], })); - assert_eq!(names(&list), ["compact", "clear-todos", "alpha", "zeta"]); - assert_eq!(list[2].kind, CommandKind::Skill); + assert_eq!( + names(&list), + ["compact", "clear", "clear-todos", "alpha", "zeta"] + ); + assert_eq!(list[3].kind, CommandKind::Skill); } /// What the agent publishes is untrusted: a skill cannot take a command's @@ -184,15 +191,16 @@ mod tests { let list = build(Some(Skills { skills: vec![ skill("compact", "pretends to be the command"), + skill("clear", "so does this"), skill("good", "one"), skill("good", "two"), skill("two words", "not a word"), skill("", "empty"), ], })); - assert_eq!(names(&list), ["compact", "clear-todos", "good"]); + assert_eq!(names(&list), ["compact", "clear", "clear-todos", "good"]); assert_eq!(list[0].kind, CommandKind::Command); - assert_eq!(list[2].description, "one"); + assert_eq!(list[3].description, "one"); } #[test] diff --git a/swarm-controller/src/agent_control.rs b/swarm-controller/src/agent_control.rs index 2bc02f0cb..67fec532b 100644 --- a/swarm-controller/src/agent_control.rs +++ b/swarm-controller/src/agent_control.rs @@ -112,6 +112,50 @@ pub(crate) async fn post_agent_cancel( send(&client, &agent, &from, AgentControl::Cancel).await } +/// Start an agent's next turn on a fresh claude session. +#[utoipa::path( + post, + path = "/api/agents/{name}/new-session", + params(("name" = String, Path, description = "agent whose next turn starts a new session")), + responses( + (status = 200, description = "the agent answered and queued the reset, which takes \ + effect at its next turn; `acted` is true", body = CancelResponse), + (status = 400, description = "the agent name is not shaped like an identifier \ + (problem+json)", body = String), + (status = 401, description = "the request carries no `Remote-User` (problem+json)", + body = String), + (status = 503, description = "the agent's harness is not subscribed - not running, \ + or not connected to the swarm queue - or no swarm queue is configured on this \ + host or it could not be reached (problem+json)", body = String), + (status = 504, description = "the harness held the command and did not answer in \ + time, so whether it took effect is unknown (problem+json)", body = String), + (status = 500, description = "the queue refused or failed the request (problem+json)", + body = String), + ), + tag = "agents" +)] +pub(crate) async fn post_agent_new_session( + State(state): State, + Path(agent): Path, + headers: HeaderMap, +) -> Result, ProblemDetails> { + let (agent, from) = target(&headers, &agent).map_err(|(s, d)| error_problem(s, d))?; + let Some(status) = state.status.as_ref() else { + return Err(error_problem( + StatusCode::SERVICE_UNAVAILABLE, + "no swarm queue is configured on this host", + )); + }; + let client = status.queue_client(); + swarm_queue_client::ensure_connected(&client).map_err(|e| { + error_problem( + StatusCode::SERVICE_UNAVAILABLE, + &swarm_queue_client::chain(&e), + ) + })?; + send(&client, &agent, &from, AgentControl::NewSession).await +} + /// The agent and who is asking, or the refusal. Everything decided before the /// queue is touched. pub(crate) fn target( @@ -160,7 +204,7 @@ async fn send( Err(error_problem( StatusCode::GATEWAY_TIMEOUT, &format!( - "{agent} did not answer in time: whether anything was cancelled is unknown" + "{agent} did not answer in time: whether the command took effect is unknown" ), )) } diff --git a/swarm-controller/src/startup.rs b/swarm-controller/src/startup.rs index 987d3ceb2..1b96b0109 100644 --- a/swarm-controller/src/startup.rs +++ b/swarm-controller/src/startup.rs @@ -674,6 +674,7 @@ pub(crate) fn build_app(state: AppState) -> axum::Router { .routes(routes!(agent_input::post_agent_input)) .routes(routes!(agent_input::post_agents_broadcast)) .routes(routes!(agent_control::post_agent_cancel)) + .routes(routes!(agent_control::post_agent_new_session)) .routes(routes!(agent_custom::post_agent_custom)) .routes(routes!(schedules::list_schedules, schedules::add_schedule)) .routes(routes!( diff --git a/swarm-queue-client/src/lib.rs b/swarm-queue-client/src/lib.rs index b254485e7..dee6a3d5c 100644 --- a/swarm-queue-client/src/lib.rs +++ b/swarm-queue-client/src/lib.rs @@ -448,6 +448,11 @@ pub enum AgentControl { /// Interrupt the turn in flight, as the agent's own cancel button does. /// Answered with an [`AgentControlReply`]. Cancel, + /// Start the next turn on a fresh claude session instead of resuming the + /// current one; the swarm UI's `/clear`. Deferred to the turn boundary + /// like the harness's own reset. Answered with an [`AgentControlReply`] + /// whose `acted` is always `true`. + NewSession, /// Apply a diff to the agent's `AGENTS.md`. Answered with an /// [`agents_md::ApplyReply`]. ApplyAgentsMd(agents_md::Apply), @@ -462,7 +467,7 @@ pub enum AgentControl { #[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)] pub struct AgentControlReply { /// Whether the command changed anything: `false` for a cancel that - /// found no turn in flight. + /// found no turn in flight. A [`AgentControl::NewSession`] always acts. pub acted: bool, }