Watch
0
0
Fork
You've already forked hyperhive
0

swarm ui: one slider for the fresh-session threshold and the soft context limit

This commit is contained in:
iris 2026-11-16 10:50:13 +01:00
commit b16074e76b
8 changed files with 450 additions and 18 deletions

View file

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

View file

@ -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 })}
/>
<TextField
id={`${idPrefix}-soft-context`}
label="soft context limit (%)"
value={draft.softContext}
placeholder="empty for the agent's own"
pattern="[0-9]*"
onInput={(softContext) => onChange({ ...draft, softContext })}
<ContextLimits
idPrefix={idPrefix}
fresh={draft.freshSession}
soft={draft.softContext}
onChange={(limits) => onChange({ ...draft, ...limits })}
/>
{problem ? <Hint tone="error">{problem}</Hint> : null}
</>
@ -300,6 +310,17 @@ export function AgentInference({ agent }: { agent: string }) {
}
/>
</li>
<li>
<Badge
label="fresh-session threshold"
value={
configured?.fresh_session_percent === undefined
? "its own"
: `${configured.fresh_session_percent}%`
}
title="a turn that finds the prompt cache cold starts a fresh session once the context is past this share of the window"
/>
</li>
<li>
<Badge
label="soft context limit"
@ -315,7 +336,7 @@ export function AgentInference({ agent }: { agent: string }) {
<Badge
variant="quiet"
value="edit"
title={`set the swarm's model, effort, subagent models, subagent cap and soft context limit for ${agent}`}
title={`set the swarm's model, effort, subagent models, subagent cap and context limits for ${agent}`}
onClick={() => setEditing(true)}
/>
</div>
@ -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<ProblemDetails | null>(null);
@ -395,10 +417,12 @@ function InferenceForm({
<Panel title={`inference — ${agent}`} icon="🧠" onClose={onClose}>
<p>
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.
</p>

View file

@ -0,0 +1,142 @@
/* <ContextLimits> — 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;
}

View file

@ -0,0 +1,115 @@
// <ContextLimits> — 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 (
<fieldset class="ui-context-limits">
<legend>context limits</legend>
<div
class="ui-context-limits-track"
style={{
"--fresh": `${limits.fresh}%`,
"--soft": `${limits.soft}%`,
}}
>
<div class="ui-context-limits-zones" aria-hidden="true" />
<input
id={`${idPrefix}-fresh-session`}
class={`ui-context-limits-handle ui-context-limits-fresh${limits.freshSet ? "" : " ui-context-limits-default"}`}
type="range"
min={MIN_SOFT_CONTEXT_PERCENT}
max={MAX_SOFT_CONTEXT_PERCENT}
step={1}
value={limits.fresh}
aria-label="fresh-session threshold, percent of the context window"
onInput={(e) => {
const to = clampFresh(Number(e.currentTarget.value), limits);
// Keep the thumb where the clamp put it when the value is unchanged.
e.currentTarget.value = String(to);
set(String(to), soft);
}}
/>
<input
id={`${idPrefix}-soft-context`}
class={`ui-context-limits-handle ui-context-limits-soft${limits.softSet ? "" : " ui-context-limits-default"}`}
type="range"
min={MIN_SOFT_CONTEXT_PERCENT}
max={MAX_SOFT_CONTEXT_PERCENT}
step={1}
value={limits.soft}
aria-label="soft context limit, percent of the context window"
onInput={(e) => {
const to = clampSoft(Number(e.currentTarget.value), limits);
e.currentTarget.value = String(to);
set(fresh, String(to));
}}
/>
</div>
<ul class="ui-context-limits-legend">
<li class="ui-context-limits-legend-fresh">
<span class="ui-context-limits-name">
a cold-cache turn starts fresh above {limits.fresh}%
</span>
<span class="ui-context-limits-source">
{limits.freshSet
? "set by the swarm"
: `the agent's own (${DEFAULT_FRESH_SESSION_PERCENT}%)`}
</span>
{limits.freshSet ? (
<button type="button" onClick={() => set("", soft)}>
use its own
</button>
) : null}
</li>
<li class="ui-context-limits-legend-soft">
<span class="ui-context-limits-name">
compacts above {limits.soft}%
</span>
<span class="ui-context-limits-source">
{limits.softSet
? "set by the swarm"
: `the agent's own (${DEFAULT_SOFT_CONTEXT_PERCENT}%)`}
</span>
{limits.softSet ? (
<button type="button" onClick={() => set(fresh, "")}>
use its own
</button>
) : null}
</li>
</ul>
</fieldset>
);
}

View file

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

View file

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

View file

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

View file

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