diff --git a/docs/4-implementation/web-ui/swarm-ui.md b/docs/4-implementation/web-ui/swarm-ui.md index d9de124ad..146221eaf 100644 --- a/docs/4-implementation/web-ui/swarm-ui.md +++ b/docs/4-implementation/web-ui/swarm-ui.md @@ -745,10 +745,10 @@ An opened agent card shows, in its **settings** section, its model and effort un with where it comes from: the swarm, its agent.nix, its own pick, or the default. Below them are the subagent model list the swarm sets, or "its own" when it sets none, the subagent cap, which reads "no cap" when unset, and the -soft context limit, which reads "its own" when unset. **edit** opens a dialog with the five fields, filled with what the swarm +fresh-session threshold and the soft context limit, which each read "its own" when unset. **edit** opens a dialog with the fields, filled with what the swarm stores; saving does a `PUT /api/agents/{agent}/inference` of the whole value. A field you leave empty stays out of it, so the agent keeps -its own value for that field; an empty max subagents is no cap, and an empty soft context limit leaves the agent's own. The soft context limit is a whole percent from 5 to 100 of the model's context window: the agent compacts at the end of a turn once its context passes it, and a turn can run past it. **clear the swarm's setting** sends the `DELETE`. +its own value for that field; an empty max subagents is no cap, and the two context limits share one slider with two handles on the model's context window, from 5 to 100 percent: a turn that finds the prompt cache cold starts a fresh session once the context passes the left (green) handle, and the agent compacts at the end of a turn once it passes the right (purple) one, and a turn can run past it. The handles can't cross. A handle the swarm hasn't set sits at the harness's own value (50 and 75) and is dimmed; **use its own** on its line puts it back there, which leaves that field out of the `PUT`. **clear the swarm's setting** sends the `DELETE`. The card reads `GET /api/agents/{agent}/inference`; before the agent's first report reaches the controller, it shows the swarm's stored values only. [inference](../swarm/inference.md) describes the settings themselves. diff --git a/frontend/packages/swarm-ui/src/agent/detail/AgentInference.tsx b/frontend/packages/swarm-ui/src/agent/detail/AgentInference.tsx index 630001e9c..93047a233 100644 --- a/frontend/packages/swarm-ui/src/agent/detail/AgentInference.tsx +++ b/frontend/packages/swarm-ui/src/agent/detail/AgentInference.tsx @@ -25,10 +25,12 @@ import { Button } from "../../ui/button/Button.js"; import { FormStack } from "../../ui/form-stack/FormStack.js"; import "../../ui/badge-row/BadgeRow.css"; import "./AgentInference.css"; +import { ContextLimits } from "./ContextLimits.js"; import { MAX_SUBAGENTS, maxSubagentsValue } from "./max-subagents.js"; import { MAX_SOFT_CONTEXT_PERCENT, MIN_SOFT_CONTEXT_PERCENT, + crossProblem, softContextValue, } from "./soft-context.js"; @@ -41,6 +43,7 @@ interface Settings { subagent_models?: string[]; max_subagents?: number; soft_context_percent?: number; + fresh_session_percent?: number; } // Mirrors `EffectiveInference`. @@ -95,6 +98,7 @@ export interface InferenceDraft { subagents: string; maxSubagents: string; softContext: string; + freshSession: string; } export const EMPTY_INFERENCE_DRAFT: InferenceDraft = { @@ -103,6 +107,7 @@ export const EMPTY_INFERENCE_DRAFT: InferenceDraft = { subagents: "", maxSubagents: "", softContext: "", + freshSession: "", }; // Why the draft would be refused, or null when it is fine to send. @@ -117,7 +122,11 @@ export function draftProblem(d: InferenceDraft): string | null { : null) ?? (softContextValue(d.softContext) === null ? `soft context limit is a whole percent from ${MIN_SOFT_CONTEXT_PERCENT} to ${MAX_SOFT_CONTEXT_PERCENT}, or empty for the agent's own` - : null) + : null) ?? + (softContextValue(d.freshSession) === null + ? `fresh-session threshold is a whole percent from ${MIN_SOFT_CONTEXT_PERCENT} to ${MAX_SOFT_CONTEXT_PERCENT}, or empty for the agent's own` + : null) ?? + crossProblem(d.freshSession, d.softContext) ); } @@ -127,7 +136,8 @@ export function draftIsEmpty(d: InferenceDraft): boolean { d.effort === "" && parseModels(d.subagents).length === 0 && d.maxSubagents.trim() === "" && - d.softContext.trim() === "" + d.softContext.trim() === "" && + d.freshSession.trim() === "" ); } @@ -142,6 +152,8 @@ export function draftBody(d: InferenceDraft): Settings { if (typeof max === "number") body.max_subagents = max; const soft = softContextValue(d.softContext); if (typeof soft === "number") body.soft_context_percent = soft; + const fresh = softContextValue(d.freshSession); + if (typeof fresh === "number") body.fresh_session_percent = fresh; return body; } @@ -188,13 +200,11 @@ export function InferenceFields({ pattern="[0-9]*" onInput={(maxSubagents) => onChange({ ...draft, maxSubagents })} /> - onChange({ ...draft, softContext })} + onChange({ ...draft, ...limits })} /> {problem ? {problem} : null} @@ -300,6 +310,17 @@ export function AgentInference({ agent }: { agent: string }) { } /> +
  • + +
  • setEditing(true)} /> @@ -359,6 +380,7 @@ function InferenceForm({ subagents: (configured?.subagent_models ?? []).join(", "), maxSubagents: configured?.max_subagents?.toString() ?? "", softContext: configured?.soft_context_percent?.toString() ?? "", + freshSession: configured?.fresh_session_percent?.toString() ?? "", }); const [busy, setBusy] = useState(false); const [problem, setProblem] = useState(null); @@ -395,10 +417,12 @@ function InferenceForm({

    Sets what the swarm makes {agent} run on. A field left empty stays the - agent's own value; an empty max subagents is no cap. The soft context - limit is a share of the context window: the agent compacts at the end of - a turn once it is past it, and a turn can run past it. The agent picks a - change up within seconds; a turn already running finishes on what it + agent's own value; an empty max subagents is no cap. The two context + limits are shares of the context window: a turn that finds the prompt + cache cold starts a fresh session once the context is past the + fresh-session threshold, and the agent compacts at the end of a turn + once it is past the soft limit (a turn can run past it). The agent picks + a change up within seconds; a turn already running finishes on what it started with, and subagents already running past a lowered cap keep running.

    diff --git a/frontend/packages/swarm-ui/src/agent/detail/ContextLimits.css b/frontend/packages/swarm-ui/src/agent/detail/ContextLimits.css new file mode 100644 index 000000000..9984cddbd --- /dev/null +++ b/frontend/packages/swarm-ui/src/agent/detail/ContextLimits.css @@ -0,0 +1,142 @@ +/* — one track with three zones and two thumbs over it. */ +.ui-context-limits { + box-sizing: border-box; + width: 100%; + min-width: 0; + margin: 0; + padding: 0.6em 0.8em 0.8em; + border: 1px solid var(--border); + border-radius: 0.5em; +} +.ui-context-limits legend { + padding: 0 0.4em; + color: var(--muted); +} + +.ui-context-limits-track { + position: relative; + height: 1.8em; + margin: 0.4em 0 0.6em; +} + +/* The zones: a turn resumes, a cold-cache turn starts fresh (from the green + handle), and the agent compacts (from the purple one). */ +.ui-context-limits-zones { + position: absolute; + inset-inline: 0; + top: 50%; + height: 0.6em; + transform: translateY(-50%); + border-radius: 0.3em; + background: linear-gradient( + to right, + color-mix(in srgb, var(--muted) 40%, transparent) 0 var(--fresh), + color-mix(in srgb, var(--green) 60%, transparent) var(--fresh) var(--soft), + color-mix(in srgb, var(--purple) 65%, transparent) var(--soft) 100% + ); +} + +/* Two sliders stacked: only the thumbs take the pointer. */ +.ui-context-limits-handle { + position: absolute; + inset: 0; + width: 100%; + margin: 0; + background: none; + pointer-events: none; + -webkit-appearance: none; + appearance: none; +} +.ui-context-limits-handle::-webkit-slider-runnable-track { + background: none; + height: 100%; +} +.ui-context-limits-handle::-moz-range-track { + background: none; +} +.ui-context-limits-handle::-webkit-slider-thumb { + pointer-events: auto; + -webkit-appearance: none; + appearance: none; + width: 1em; + height: 1.6em; + border: 2px solid var(--fg); + border-radius: 0.35em; + background: var(--bg-elev); + cursor: grab; +} +.ui-context-limits-handle::-moz-range-thumb { + pointer-events: auto; + width: 0.8em; + height: 1.4em; + border: 2px solid var(--fg); + border-radius: 0.35em; + background: var(--bg-elev); + cursor: grab; +} +.ui-context-limits-fresh::-webkit-slider-thumb { + border-color: var(--green); +} +.ui-context-limits-fresh::-moz-range-thumb { + border-color: var(--green); +} +.ui-context-limits-soft::-webkit-slider-thumb { + border-color: var(--purple); +} +.ui-context-limits-soft::-moz-range-thumb { + border-color: var(--purple); +} +/* A handle the swarm has not set sits at the harness's own default, dimmed. */ +.ui-context-limits-default::-webkit-slider-thumb { + opacity: 0.55; + border-style: dashed; +} +.ui-context-limits-default::-moz-range-thumb { + opacity: 0.55; + border-style: dashed; +} +.ui-context-limits-handle:focus-visible::-webkit-slider-thumb { + outline: 2px solid var(--blue); + outline-offset: 2px; +} +.ui-context-limits-handle:focus-visible::-moz-range-thumb { + outline: 2px solid var(--blue); + outline-offset: 2px; +} + +.ui-context-limits-legend { + display: flex; + flex-direction: column; + gap: 0.3em; + margin: 0; + padding: 0; + list-style: none; +} +.ui-context-limits-legend li { + display: flex; + flex-wrap: wrap; + align-items: baseline; + gap: 0.2em 0.75em; + padding-inline-start: 0.6em; + border-inline-start: 3px solid transparent; +} +.ui-context-limits-legend-fresh { + border-inline-start-color: var(--green); +} +.ui-context-limits-legend-soft { + border-inline-start-color: var(--purple); +} +.ui-context-limits-source { + color: var(--muted); + font-size: 0.85em; +} +.ui-context-limits-legend button { + padding: 0; + border: 0; + background: none; + color: var(--blue); + font: inherit; + font-size: 0.85em; + text-decoration: underline; + cursor: pointer; +} diff --git a/frontend/packages/swarm-ui/src/agent/detail/ContextLimits.tsx b/frontend/packages/swarm-ui/src/agent/detail/ContextLimits.tsx new file mode 100644 index 000000000..042d50cfe --- /dev/null +++ b/frontend/packages/swarm-ui/src/agent/detail/ContextLimits.tsx @@ -0,0 +1,115 @@ +// — the fresh-session threshold and the soft context limit as +// one slider with two handles on the share of the context window. Left of the +// first handle a turn resumes its session; between the handles a turn that +// finds the prompt cache cold starts a fresh one; right of the second the +// agent compacts. The handles cannot cross (`soft-context.ts`). A handle the +// swarm has not set shows the harness's own default and is dimmed; `use its +// own` puts one back there. +// +// Two native range inputs sit one over the other, so the keyboard and screen +// readers get two sliders; the track and its three zones are drawn behind them. +import { + clampFresh, + clampSoft, + DEFAULT_FRESH_SESSION_PERCENT, + DEFAULT_SOFT_CONTEXT_PERCENT, + limitsOf, + MAX_SOFT_CONTEXT_PERCENT, + MIN_SOFT_CONTEXT_PERCENT, +} from "./soft-context.js"; +import "./ContextLimits.css"; + +export function ContextLimits({ + fresh, + soft, + onChange, + idPrefix, +}: { + /** The fresh-session threshold's box text: empty keeps the agent's own. */ + fresh: string; + /** The soft limit's box text: empty keeps the agent's own. */ + soft: string; + onChange: (next: { freshSession: string; softContext: string }) => void; + idPrefix: string; +}) { + const limits = limitsOf(fresh, soft); + const set = (freshSession: string, softContext: string) => + onChange({ freshSession, softContext }); + return ( +
    + context limits +
    + +
      +
    • + + a cold-cache turn starts fresh above {limits.fresh}% + + + {limits.freshSet + ? "set by the swarm" + : `the agent's own (${DEFAULT_FRESH_SESSION_PERCENT}%)`} + + {limits.freshSet ? ( + + ) : null} +
    • +
    • + + compacts above {limits.soft}% + + + {limits.softSet + ? "set by the swarm" + : `the agent's own (${DEFAULT_SOFT_CONTEXT_PERCENT}%)`} + + {limits.softSet ? ( + + ) : null} +
    • +
    +
    + ); +} diff --git a/frontend/packages/swarm-ui/src/agent/detail/soft-context.ts b/frontend/packages/swarm-ui/src/agent/detail/soft-context.ts index b5abf3218..ebf912fae 100644 --- a/frontend/packages/swarm-ui/src/agent/detail/soft-context.ts +++ b/frontend/packages/swarm-ui/src/agent/detail/soft-context.ts @@ -1,5 +1,9 @@ -// The create form's and the inference dialog's `soft_context_percent` field, -// kept out of the component so `npm test` can run it. +// The create form's and the inference dialog's context limits, kept out of the +// components so `npm test` can run them: the `soft_context_percent` field (the +// agent compacts above it) and the `fresh_session_percent` field (above it, a +// turn that finds the prompt cache cold starts a fresh session), and the slider +// that moves both. Each is the text of its box, where empty keeps the agent's +// own value. /** The lowest `soft_context_percent` the swarm accepts. */ export const MIN_SOFT_CONTEXT_PERCENT = 5; @@ -20,3 +24,75 @@ export function softContextValue(text: string): number | null | undefined { ? n : null; } + +/** What the harness uses for the fresh-session threshold when none is set. */ +export const DEFAULT_FRESH_SESSION_PERCENT = 50; +/** What the harness uses for the soft limit when none is set. */ +export const DEFAULT_SOFT_CONTEXT_PERCENT = 75; + +/** The two limits as the slider draws them. */ +export interface Limits { + /** Where the fresh-session handle sits. */ + fresh: number; + /** Where the soft-limit handle sits. */ + soft: number; + /** Whether the swarm sets the fresh-session threshold, or the agent's own applies. */ + freshSet: boolean; + /** Whether the swarm sets the soft limit. */ + softSet: boolean; +} + +function percentOf(text: string): number | undefined { + const v = softContextValue(text); + return typeof v === "number" ? v : undefined; +} + +/** + * Where the handles sit: a set value where there is one, else the harness's own + * default. An unset fresh-session threshold never sits above the soft limit + * (the agent compacts there, so the context would not get past it), and a + * typed value that is not a valid percent counts as unset. + */ +export function limitsOf(freshText: string, softText: string): Limits { + const freshValue = percentOf(freshText); + const softValue = percentOf(softText); + const soft = softValue ?? DEFAULT_SOFT_CONTEXT_PERCENT; + const fresh = freshValue ?? Math.min(DEFAULT_FRESH_SESSION_PERCENT, soft); + return { + fresh, + soft, + freshSet: freshValue !== undefined, + softSet: softValue !== undefined, + }; +} + +/** Where the fresh-session handle may go: not past the soft handle. */ +export function clampFresh(to: number, limits: Limits): number { + return Math.min( + Math.max(Math.round(to), MIN_SOFT_CONTEXT_PERCENT), + limits.soft, + ); +} + +/** Where the soft handle may go: not below the fresh-session handle. */ +export function clampSoft(to: number, limits: Limits): number { + return Math.min( + Math.max(Math.round(to), limits.fresh, MIN_SOFT_CONTEXT_PERCENT), + MAX_SOFT_CONTEXT_PERCENT, + ); +} + +/** + * Why the two boxes are refused together: a fresh-session threshold above the + * soft limit, both set. Each box's own range is `draftProblem`'s. + */ +export function crossProblem( + freshText: string, + softText: string, +): string | null { + const fresh = percentOf(freshText); + const soft = percentOf(softText); + return fresh !== undefined && soft !== undefined && fresh > soft + ? `the fresh-session threshold (${fresh}%) is above the soft limit (${soft}%): the agent compacts at the soft limit, so a fresh start above it would never happen` + : null; +} diff --git a/frontend/packages/swarm-ui/src/pages/CreateAgentArchetype.ts b/frontend/packages/swarm-ui/src/pages/CreateAgentArchetype.ts index aeb52b60a..77574990a 100644 --- a/frontend/packages/swarm-ui/src/pages/CreateAgentArchetype.ts +++ b/frontend/packages/swarm-ui/src/pages/CreateAgentArchetype.ts @@ -15,6 +15,7 @@ export interface Archetype { subagent_models?: string[]; max_subagents?: number; soft_context_percent?: number; + fresh_session_percent?: number; }; prompt?: string; /** The archetype's icon as SVG text. */ @@ -74,6 +75,10 @@ export function prefill( inference.soft_context_percent === undefined ? "" : String(inference.soft_context_percent), + freshSession: + inference.fresh_session_percent === undefined + ? "" + : String(inference.fresh_session_percent), }, }; } diff --git a/frontend/packages/swarm-ui/test/context-limits.test.mjs b/frontend/packages/swarm-ui/test/context-limits.test.mjs new file mode 100644 index 000000000..65e618c5c --- /dev/null +++ b/frontend/packages/swarm-ui/test/context-limits.test.mjs @@ -0,0 +1,68 @@ +// The two context limits behind the slider: where the handles sit, how far +// each may move and when the pair is refused. Run by `npm test`. +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { + clampFresh, + clampSoft, + crossProblem, + DEFAULT_FRESH_SESSION_PERCENT, + DEFAULT_SOFT_CONTEXT_PERCENT, + limitsOf, +} from "../src/agent/detail/soft-context.ts"; + +test("with nothing set the handles sit at the harness's own defaults", () => { + assert.deepEqual(limitsOf("", ""), { + fresh: DEFAULT_FRESH_SESSION_PERCENT, + soft: DEFAULT_SOFT_CONTEXT_PERCENT, + freshSet: false, + softSet: false, + }); +}); + +test("a set value moves its handle and marks it set", () => { + assert.deepEqual(limitsOf("30", "90"), { + fresh: 30, + soft: 90, + freshSet: true, + softSet: true, + }); + const onlySoft = limitsOf("", "90"); + assert.equal(onlySoft.fresh, 50); + assert.equal(onlySoft.freshSet, false); +}); + +test("an unset fresh-session handle never sits above the soft one", () => { + const l = limitsOf("", "40"); + assert.equal(l.fresh, 40); + assert.equal(l.soft, 40); +}); + +test("text that is not a valid percent counts as unset", () => { + const l = limitsOf("abc", "200"); + assert.equal(l.freshSet, false); + assert.equal(l.softSet, false); +}); + +test("the fresh-session handle stops at the soft one and at 5", () => { + const l = limitsOf("30", "60"); + assert.equal(clampFresh(45, l), 45); + assert.equal(clampFresh(80, l), 60); + assert.equal(clampFresh(1, l), 5); + assert.equal(clampFresh(44.6, l), 45); +}); + +test("the soft handle stops at the fresh-session one and at 100", () => { + const l = limitsOf("30", "60"); + assert.equal(clampSoft(75, l), 75); + assert.equal(clampSoft(10, l), 30); + assert.equal(clampSoft(150, l), 100); +}); + +test("a fresh-session threshold above the soft limit is refused, both set", () => { + assert.match(crossProblem("80", "60"), /above the soft limit/); + assert.equal(crossProblem("60", "60"), null); + assert.equal(crossProblem("30", "60"), null); + assert.equal(crossProblem("", "60"), null); + assert.equal(crossProblem("90", ""), null); +}); diff --git a/frontend/packages/swarm-ui/test/create-agent-archetype.test.mjs b/frontend/packages/swarm-ui/test/create-agent-archetype.test.mjs index ad1d59a17..2cc5408b6 100644 --- a/frontend/packages/swarm-ui/test/create-agent-archetype.test.mjs +++ b/frontend/packages/swarm-ui/test/create-agent-archetype.test.mjs @@ -21,6 +21,7 @@ const empty = { subagents: "", maxSubagents: "", softContext: "", + freshSession: "", }, }; @@ -53,6 +54,7 @@ test("an archetype's settings fill the form", () => { subagents: "haiku, sonnet", maxSubagents: "0", softContext: "20", + freshSession: "", }, }); });