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
7 changed files with 450 additions and 18 deletions

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