Watch
0
0
Fork
You've already forked hyperhive
0

swarm-ui: an editor for an agent's AGENTS.md that saves as a diff

The instructions row of the agent detail panel gets an edit button that
opens the agent's AGENTS.md, as the harness last published it, in a text
box. Save sends a unified diff against the revision that was loaded; when
the agent changed the file meanwhile the editor keeps the operator's text,
shows the agent's version and offers to save over it or take it. An unsaved
edit survives closing the dialog.

The diff is built in the browser (LCS over lines, three lines of context,
git's no-newline marker) and was checked against git apply on 600 random
before/after pairs.
This commit is contained in:
iris 2026-10-18 12:40:34 +02:00 • committed by mara
commit b5d2e310ba

View file

@ -0,0 +1,311 @@
// <AgentInstructions> — an editor for an agent's AGENTS.md, in a dialog opened
// from the agent's detail panel.
//
// It loads the copy the agent's harness last published
// (`GET /api/agents/{name}/agents-md`, so a stopped agent shows the text it
// left) into a plain text box. Save sends a unified diff against the revision
// that was loaded (`PUT`), and the agent applies it with git to the file it
// really reads. The agent may have edited the file in the meantime; then the
// swarm refuses with 409 and the editor keeps the operator's text, shows the
// agent's version beside it, and offers the two ways on: save over it, or take
// the agent's version.
//
// Closing the dialog does not lose an unsaved edit: the wrapper keeps it, and
// the next open starts from it (and notices if the agent moved on).
import { useEffect, useRef, useState } from "preact/hooks";
import { ApiErrorPanel } from "@hive/shared/api-error-panel.js";
import { readApiError, type ProblemDetails } from "@hive/shared/api-error.js";
import { Badge } from "@hive/shared/badge.js";
import { Button } from "../../ui/button/Button.js";
import { Dialog } from "../../ui/dialog/Dialog.js";
import { Panel } from "../../ui/panel/Panel.js";
import { TextAreaField } from "../../ui/text-area-field/TextAreaField.js";
import {
editBody,
instructionsUrl,
parseInstructions,
STALE_STATUS,
type Instructions,
} from "./instructions.js";
import "./AgentInstructions.css";
// An edit that was not saved: the text, and the version it was made on.
interface Unsaved {
base: Instructions;
text: string;
}
export function AgentInstructions({ agent }: { agent: string }) {
const [editing, setEditing] = useState(false);
const unsaved = useRef<Unsaved | null>(null);
return (
<>
<Badge
variant="quiet"
value="edit"
title={`read and change ${agent}'s AGENTS.md`}
onClick={() => setEditing(true)}
/>
<Dialog
open={editing}
onClose={() => setEditing(false)}
label={`edit ${agent}'s AGENTS.md`}
plain
>
{/* Remounted per open, so it starts from the kept edit or a fresh read. */}
{editing ? (
<InstructionsForm
agent={agent}
kept={unsaved.current}
onKeep={(u) => {
unsaved.current = u;
}}
onClose={() => setEditing(false)}
/>
) : null}
</Dialog>
</>
);
}
type Load =
| { status: "loading" }
| { status: "error"; problem: ProblemDetails }
| { status: "ready" };
async function fetchInstructions(agent: string): Promise<Instructions> {
const r = await fetch(instructionsUrl(agent));
if (!r.ok) throw await readApiError(r);
const parsed = parseInstructions(await r.json());
if (parsed === null) {
throw { detail: "the swarm's answer was not an AGENTS.md" };
}
return parsed;
}
function asProblem(e: unknown): ProblemDetails {
if (typeof e === "object" && e !== null) return e as ProblemDetails;
return { detail: String(e) };
}
function InstructionsForm({
agent,
kept,
onKeep,
onClose,
}: {
agent: string;
kept: Unsaved | null;
onKeep: (u: Unsaved | null) => void;
onClose: () => void;
}) {
const [load, setLoad] = useState<Load>({ status: "loading" });
// The version the draft is made against, and the draft.
const [base, setBase] = useState<Instructions | null>(null);
const [draft, setDraft] = useState("");
// The agent's version when it has moved past `base`: set when a save was
// refused as stale, or when the kept edit is older than the file.
const [theirs, setTheirs] = useState<Instructions | null>(null);
const [busy, setBusy] = useState(false);
const [problem, setProblem] = useState<ProblemDetails | null>(null);
const [saved, setSaved] = useState(false);
useEffect(() => {
let cancelled = false;
fetchInstructions(agent)
.then((current) => {
if (cancelled) return;
if (kept === null) {
setBase(current);
setDraft(current.content);
} else {
setBase(kept.base);
setDraft(kept.text);
if (current.revision !== kept.base.revision) setTheirs(current);
}
setLoad({ status: "ready" });
})
.catch((e: unknown) => {
if (!cancelled) setLoad({ status: "error", problem: asProblem(e) });
});
return () => {
cancelled = true;
};
// `kept` is only the starting point, read once when the form mounts.
}, [agent]);
const dirty = base !== null && draft !== base.content;
useEffect(() => {
if (base !== null) onKeep(dirty ? { base, text: draft } : null);
}, [base, draft, dirty]);
async function save(e: Event) {
e.preventDefault();
if (base === null) return;
const body = editBody(base, draft);
if (body === null) return;
setBusy(true);
setProblem(null);
setSaved(false);
try {
const r = await fetch(instructionsUrl(agent), {
method: "PUT",
headers: { "content-type": "application/json" },
body: JSON.stringify(body),
});
if (r.status === STALE_STATUS) {
// The agent changed the file: keep the draft, fetch what it is now.
setTheirs(await fetchInstructions(agent));
return;
}
if (!r.ok) {
setProblem(await readApiError(r));
return;
}
const answer = (await r.json()) as { revision?: unknown };
if (typeof answer.revision !== "string") {
setProblem({ detail: "the swarm's answer named no revision" });
return;
}
setBase({ content: draft, revision: answer.revision });
setSaved(true);
} catch (err: unknown) {
setProblem(asProblem(err));
} finally {
setBusy(false);
}
}
function keepMine() {
if (theirs === null) return;
setBase(theirs);
setTheirs(null);
}
function takeTheirs() {
if (theirs === null) return;
setBase(theirs);
setDraft(theirs.content);
setTheirs(null);
}
function reload() {
setLoad({ status: "loading" });
fetchInstructions(agent)
.then((current) => {
setBase(current);
setDraft(current.content);
setTheirs(null);
setProblem(null);
setLoad({ status: "ready" });
})
.catch((e: unknown) =>
setLoad({ status: "error", problem: asProblem(e) }),
);
}
return (
<Panel title={`AGENTS.md — ${agent}`} icon="📜" onClose={onClose}>
<p>
The instructions {agent} reads. This is the copy the agent last
published, so a stopped agent still shows. Saving needs the agent
running: it applies your change to its own file, and refuses when it
edited the file since you opened this.
</p>
<div class="ui-agent-instructions-body">
<p
class="ui-agent-instructions-status"
role="status"
aria-live="polite"
>
{load.status === "loading"
? "loading…"
: busy
? "saving…"
: saved
? "saved"
: ""}
</p>
{load.status === "error" ? (
<>
<ApiErrorPanel
context="loading AGENTS.md failed"
problem={load.problem}
/>
<div class="ui-agent-instructions-actions">
<Button onClick={reload}>try again</Button>
</div>
</>
) : null}
{load.status === "ready" ? (
<form class="ui-agent-instructions-form" onSubmit={save}>
<div class="ui-agent-instructions-text">
<TextAreaField
id={`agents-md-${agent}`}
label="AGENTS.md"
value={draft}
rows={16}
onInput={(text) => {
setDraft(text);
setSaved(false);
}}
/>
</div>
{theirs !== null ? (
<section class="ui-agent-instructions-stale" role="alert">
<p>
{agent} changed AGENTS.md since you started. Your text is kept
above. Here is the file now:
</p>
<pre class="ui-agent-instructions-theirs" tabIndex={0}>
{theirs.content === "" ? "(empty)" : theirs.content}
</pre>
<div class="ui-agent-instructions-actions">
<Button onClick={keepMine}>
keep my text, replace {agent}'s changes
</Button>
<Button onClick={takeTheirs}>use {agent}'s version</Button>
</div>
</section>
) : null}
{problem ? (
<ApiErrorPanel context="saving failed" problem={problem} />
) : null}
<div class="ui-agent-instructions-actions">
<Button
variant="primary"
type="submit"
disabled={busy || !dirty || theirs !== null}
>
{busy ? "saving…" : "save"}
</Button>
<Button
disabled={busy || !dirty}
onClick={() => {
if (base !== null) setDraft(base.content);
setSaved(false);
}}
>
undo my changes
</Button>
<Button
disabled={busy}
onClick={() => {
if (
!dirty ||
window.confirm(
"Drop your unsaved changes and load the agent's file?",
)
)
reload();
}}
>
reload from {agent}
</Button>
</div>
</form>
) : null}
</div>
</Panel>
);
}