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.
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).

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}`.
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.<name>`, 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.<name>`, as it sends a cancel. (The same
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
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
// 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("") },
);
}

View file

@ -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;
}

View file

@ -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);
});

View file

@ -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<F>(
payload: &[u8],
cancel: impl FnOnce() -> bool,
new_session: impl FnOnce(),
apply: impl FnOnce(swarm_queue_client::agents_md::Apply) -> F,
) -> Option<Vec<u8>>
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);
}
}

View file

@ -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]

View file

@ -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<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
/// 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"
),
))
}

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_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!(

View file

@ -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,
}