Watch
0
0
Fork
You've already forked hyperhive
0

swarm: /clear starts an agent's next turn on a fresh session

This commit is contained in:
iris 2026-11-16 01:01:31 +01:00
commit fb9d4b5040
10 changed files with 155 additions and 22 deletions

View file

@ -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. the agent's own list within a few seconds.
Type `/` in an agent's message box and a menu lists what that agent accepts: 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 the swarm's own commands and the skills the agent's harness published. Arrow
agent's harness published. Arrow keys move, Tab completes, Esc closes. Skills keys move, Tab completes, Esc closes. Skills are per agent, so two agents can
are per agent, so two agents can offer different lists. `/clear-todos` marks all offer different lists. The swarm's commands are `/compact`, which compacts the
of the agent's todos done without starting a turn, and the terminal shows how agent's context after its current turn; `/clear`, which starts its next turn on
many it cleared. 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 Each page, its controls and what they send are in
[the swarm UI reference](../../4-implementation/web-ui/swarm-ui.md). [the swarm UI reference](../../4-implementation/web-ui/swarm-ui.md).

View file

@ -356,8 +356,10 @@ The text holds no secret, so nothing goes through the secret store.
**Editing.** `PUT /api/agents/<name>/agents-md` takes `{base_revision, diff}`. **Editing.** `PUT /api/agents/<name>/agents-md` takes `{base_revision, diff}`.
The diff is a unified diff that names `a/AGENTS.md` and `b/AGENTS.md`, made 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 against the text at `base_revision`. swarm-controller sends it as a request on
the agent's command subject `$SWARM.control.<name>`, as it sends a cancel. The the agent's command subject `$SWARM.control.<name>`, as it sends a cancel. (The same
harness refuses it when the file isn't at `base_revision`. Otherwise it runs subject carries `POST /api/agents/<name>/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 `git apply --check` and then `git apply` on a copy of the file, and writes the
result over the file only when both pass: result over the file only when both pass:

View file

@ -4,6 +4,10 @@
// sees it as an inbox turn from the logged-in user (the controller takes the // sees it as an inbox turn from the logged-in user (the controller takes the
// sender from the gateway, not from this request). // 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 // 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 // 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 // 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 { CommandMenu } from "./CommandMenu.js";
import { import {
completion, completion,
controlRoute,
enterSends, enterSends,
matchCommands, matchCommands,
menuQuery, menuQuery,
@ -47,13 +52,17 @@ export function AgentInputForm({ agentName }: { agentName: string }) {
function submit(e: Event) { function submit(e: Event) {
e.preventDefault(); e.preventDefault();
const base = `/api/agents/${encodeURIComponent(agentName)}`;
const route = controlRoute(body, commands);
void run( void run(
() => () =>
fetch(`/api/agents/${encodeURIComponent(agentName)}/input`, { route
method: "POST", ? fetch(`${base}/${route}`, { method: "POST" })
headers: { "content-type": "application/json" }, : fetch(`${base}/input`, {
body: JSON.stringify({ body }), method: "POST",
}), headers: { "content-type": "application/json" },
body: JSON.stringify({ body }),
}),
{ onDone: () => setBody("") }, { onDone: () => setBody("") },
); );
} }

View file

@ -92,3 +92,19 @@ export function moveSelection(
export function enterSends(text: string, selected: AgentCommand): boolean { export function enterSends(text: string, selected: AgentCommand): boolean {
return text.trim() === `/${selected.name}`; 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;
}

View file

@ -4,6 +4,7 @@ import assert from "node:assert/strict";
import { test } from "node:test"; import { test } from "node:test";
import { import {
completion, completion,
controlRoute,
enterSends, enterSends,
matchCommands, matchCommands,
menuQuery, 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("/comp", cmd("compact")), false);
assert.equal(enterSends("/", 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);
});

View file

@ -81,6 +81,13 @@ async fn run_control(
let Some(answer) = act( let Some(answer) = act(
&msg.payload, &msg.payload,
|| crate::web_ui::cancel_turn(&bus, &interrupted, "swarm UI: cancel"), || 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, crate::swarm_agents_md::handle,
) )
.await .await
@ -93,12 +100,13 @@ async fn run_control(
} }
} }
/// The encoded answer to a command payload: `cancel` runs for a cancel and /// The encoded answer to a command payload: `cancel` runs for a cancel,
/// `apply` for an `AGENTS.md` edit. `None` (logged) when the payload is not a /// `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. /// command, which gets no answer.
async fn act<F>( async fn act<F>(
payload: &[u8], payload: &[u8],
cancel: impl FnOnce() -> bool, cancel: impl FnOnce() -> bool,
new_session: impl FnOnce(),
apply: impl FnOnce(swarm_queue_client::agents_md::Apply) -> F, apply: impl FnOnce(swarm_queue_client::agents_md::Apply) -> F,
) -> Option<Vec<u8>> ) -> Option<Vec<u8>>
where where
@ -110,6 +118,10 @@ where
Ok(AgentControl::Cancel) => { Ok(AgentControl::Cancel) => {
serde_json::to_vec(&swarm_queue_client::AgentControlReply { acted: 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), Ok(AgentControl::ApplyAgentsMd(edit)) => serde_json::to_vec(&apply(edit).await),
Err(e) => { Err(e) => {
tracing::warn!(error = %e, "swarm control: undecodable command dropped"); tracing::warn!(error = %e, "swarm control: undecodable command dropped");
@ -321,6 +333,7 @@ mod tests {
let got = act( let got = act(
br#""cancel""#, br#""cancel""#,
|| acted, || acted,
|| panic!("reset the session for a cancel"),
|_| async { panic!("applied an edit for a cancel") }, |_| async { panic!("applied an edit for a cancel") },
) )
.await .await
@ -341,6 +354,7 @@ mod tests {
let got = act( let got = act(
&payload, &payload,
|| panic!("cancelled for an edit"), || panic!("cancelled for an edit"),
|| panic!("reset the session for an edit"),
|got| async move { |got| async move {
assert_eq!(got, edit); assert_eq!(got, edit);
ApplyReply::Applied { ApplyReply::Applied {
@ -364,9 +378,26 @@ mod tests {
let got = act( let got = act(
b"pause", b"pause",
|| panic!("ran a command that was not one"), || 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") }, |_| async { panic!("ran a command that was not one") },
) )
.await; .await;
assert_eq!(got, None); 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);
}
} }

View file

@ -18,11 +18,15 @@ use crate::routes::AppState;
/// The commands the swarm UI offers every agent: the name without the slash, /// The commands the swarm UI offers every agent: the name without the slash,
/// and what it does. /// and what it does.
const COMMANDS: [(&str, &str); 2] = [ const COMMANDS: [(&str, &str); 3] = [
( (
"compact", "compact",
"Compact this agent's context after the current turn", "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"), ("clear-todos", "Mark all of this agent's todos done"),
]; ];
@ -164,7 +168,7 @@ mod tests {
#[test] #[test]
fn the_swarms_commands_come_first_and_always() { fn the_swarms_commands_come_first_and_always() {
let list = build(None); 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)); assert!(list.iter().all(|e| e.kind == CommandKind::Command));
} }
@ -173,8 +177,11 @@ mod tests {
let list = build(Some(Skills { let list = build(Some(Skills {
skills: vec![skill("zeta", "z"), skill("alpha", "a")], skills: vec![skill("zeta", "z"), skill("alpha", "a")],
})); }));
assert_eq!(names(&list), ["compact", "clear-todos", "alpha", "zeta"]); assert_eq!(
assert_eq!(list[2].kind, CommandKind::Skill); 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 /// What the agent publishes is untrusted: a skill cannot take a command's
@ -184,15 +191,16 @@ mod tests {
let list = build(Some(Skills { let list = build(Some(Skills {
skills: vec![ skills: vec![
skill("compact", "pretends to be the command"), skill("compact", "pretends to be the command"),
skill("clear", "so does this"),
skill("good", "one"), skill("good", "one"),
skill("good", "two"), skill("good", "two"),
skill("two words", "not a word"), skill("two words", "not a word"),
skill("", "empty"), 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[0].kind, CommandKind::Command);
assert_eq!(list[2].description, "one"); assert_eq!(list[3].description, "one");
} }
#[test] #[test]

View file

@ -112,6 +112,50 @@ pub(crate) async fn post_agent_cancel(
send(&client, &agent, &from, AgentControl::Cancel).await 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<AppState>,
Path(agent): Path<String>,
headers: HeaderMap,
) -> Result<Json<CancelResponse>, 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 /// The agent and who is asking, or the refusal. Everything decided before the
/// queue is touched. /// queue is touched.
pub(crate) fn target( pub(crate) fn target(
@ -160,7 +204,7 @@ async fn send(
Err(error_problem( Err(error_problem(
StatusCode::GATEWAY_TIMEOUT, StatusCode::GATEWAY_TIMEOUT,
&format!( &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"
), ),
)) ))
} }

View file

@ -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_agent_input))
.routes(routes!(agent_input::post_agents_broadcast)) .routes(routes!(agent_input::post_agents_broadcast))
.routes(routes!(agent_control::post_agent_cancel)) .routes(routes!(agent_control::post_agent_cancel))
.routes(routes!(agent_control::post_agent_new_session))
.routes(routes!(agent_custom::post_agent_custom)) .routes(routes!(agent_custom::post_agent_custom))
.routes(routes!(schedules::list_schedules, schedules::add_schedule)) .routes(routes!(schedules::list_schedules, schedules::add_schedule))
.routes(routes!( .routes(routes!(

View file

@ -448,6 +448,11 @@ pub enum AgentControl {
/// Interrupt the turn in flight, as the agent's own cancel button does. /// Interrupt the turn in flight, as the agent's own cancel button does.
/// Answered with an [`AgentControlReply`]. /// Answered with an [`AgentControlReply`].
Cancel, 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 /// Apply a diff to the agent's `AGENTS.md`. Answered with an
/// [`agents_md::ApplyReply`]. /// [`agents_md::ApplyReply`].
ApplyAgentsMd(agents_md::Apply), ApplyAgentsMd(agents_md::Apply),
@ -462,7 +467,7 @@ pub enum AgentControl {
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)] #[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct AgentControlReply { pub struct AgentControlReply {
/// Whether the command changed anything: `false` for a cancel that /// 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, pub acted: bool,
} }