Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

feat(ui): set and keep local agent token limits per model

Bernhard Jackiewicz9e27ae3048fd
diff --git a/graph-ui/src/browser-ai/BrowserChatDock.test.tsx b/graph-ui/src/browser-ai/BrowserChatDock.test.tsx
index 97f82efeb..fc8f834c1 100644
--- a/graph-ui/src/browser-ai/BrowserChatDock.test.tsx
+++ b/graph-ui/src/browser-ai/BrowserChatDock.test.tsx
@@ -4,6 +4,7 @@ import { createRoot, type Root } from 'react-dom/client';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import BrowserChatDock, { type BrowserChatAttachment, type BrowserChatDockProps, type BrowserChatReaderContext } from './BrowserChatDock';
import type { BrowserAiProgress, BrowserChatMessage } from './browser-ai-runtime';
+import type { BrowserChatOptions } from './browser-ai-controller';
import { BROWSER_MODELS } from './model-policy';
import { JSONB_AGG_CALLERS, jsonbAggEvidence, jsonbAggScope } from './galaxy-evidence.fixture';
@@ -12,6 +13,8 @@ let root: Root;
let renderedProps: BrowserChatDockProps;
beforeEach(() => {
(globalThis as unknown as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+ // Agent preferences persist in this browser; every test starts from the defaults.
+ window.localStorage.clear();
container = document.createElement('div'); document.body.appendChild(container); root = createRoot(container);
});
afterEach(async () => { await act(async () => root.unmount()); container.remove(); vi.restoreAllMocks(); });
@@ -23,7 +26,7 @@ function fixture() {
prepare: vi.fn(async (_progress: (value: BrowserAiProgress) => void) => {}),
explain: vi.fn(async () => 'Legacy'),
countTokens: vi.fn(async (_messages: readonly BrowserChatMessage[]) => 100),
- chat: vi.fn(async (_messages: readonly BrowserChatMessage[], _onToken: (chunk: string) => void) => 'Adds the two values.'),
+ chat: vi.fn(async (_messages: readonly BrowserChatMessage[], _onToken: (chunk: string) => void, _options?: BrowserChatOptions) => 'Adds the two values.'),
stop: vi.fn(), dispose: vi.fn(),
};
const props = { proactive: false, open: true, onClose: vi.fn(), onAttachmentConsumed: vi.fn(), onAttachmentRemoved: vi.fn(), createRuntime: vi.fn(() => runtime), removeCache: vi.fn(async () => {}) };
@@ -909,7 +912,7 @@ describe('graph answers and answer limits', () => {
it('marks an answer cut at the output token limit and shows the capacity of an oversized scope', async () => {
const { props, runtime } = fixture();
- runtime.chat.mockImplementationOnce(async (_messages, _onToken, options?: { onComplete?: (result: { stopReason: 'length' | 'eos' }) => void }) => {
+ runtime.chat.mockImplementationOnce(async (_messages, _onToken, options) => {
options?.onComplete?.({ stopReason: 'length' }); return 'A long list that';
});
const many = Array.from({ length: 40 }, (_, index) => ({ source: 2000 + index, target: 32360, type: 'CALLS' }));
@@ -993,3 +996,72 @@ describe('per-selection explanation cache', () => {
expect(runtime.chat).toHaveBeenCalledTimes(35);
});
});
+
+
+describe('agent configuration limits', () => {
+ afterEach(() => vi.useRealTimers());
+ async function setLimit(id: string, value: number): Promise<void> {
+ const input = document.querySelector<HTMLInputElement>(`#${id}`)!;
+ await act(async () => {
+ Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')!.set!.call(input, String(value));
+ input.dispatchEvent(new Event('input', { bubbles: true }));
+ });
+ await act(async () => input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true })));
+ }
+ const field = (id: string) => document.querySelector<HTMLInputElement>(`#${id}`);
+
+ it('offers input and output limits per model within the model policy', async () => {
+ const { props } = fixture(); await render(props); await models();
+ const [first] = BROWSER_MODELS;
+ expect(document.querySelector('.cbm-chat-token-limits legend')?.textContent).toBe(`Token limits for ${first.displayName}`);
+ expect(field('cbm-chat-input-tokens')).toMatchObject({ value: '2048', min: '512', max: String(first.contextTokens - first.maxOutputTokens) });
+ expect(field('cbm-chat-output-tokens')).toMatchObject({ value: String(first.maxOutputTokens), min: '32', max: String(first.maxOutputTokens) });
+ await setLimit('cbm-chat-output-tokens', 99_999);
+ expect(field('cbm-chat-output-tokens')?.value).toBe(String(first.maxOutputTokens));
+ await setLimit('cbm-chat-output-tokens', 128);
+ expect(field('cbm-chat-input-tokens')?.max).toBe(String(first.contextTokens - 128));
+ });
+
+ it('keeps the chosen model, automatic explanations and limits across a reload', async () => {
+ const { props } = fixture(); await render({ ...props, proactive: true }); await models();
+ const [first, second] = BROWSER_MODELS;
+ await setLimit('cbm-chat-output-tokens', 256);
+ const select = document.querySelector<HTMLSelectElement>('#cbm-chat-model')!;
+ await act(async () => { select.value = second.id; select.dispatchEvent(new Event('change', { bubbles: true })); });
+ await setLimit('cbm-chat-input-tokens', 3072);
+ const automatic = [...document.querySelectorAll('label')].find(label => label.textContent?.includes('Explain selections automatically'))!.querySelector('input')!;
+ await act(async () => automatic.click());
+ await act(async () => root.unmount());
+ root = createRoot(container);
+ await render({ ...props, proactive: true }); await models();
+ expect(document.querySelector<HTMLSelectElement>('#cbm-chat-model')?.value).toBe(second.id);
+ expect(field('cbm-chat-input-tokens')?.value).toBe('3072');
+ expect(field('cbm-chat-output-tokens')?.value).toBe(String(second.maxOutputTokens));
+ expect([...document.querySelectorAll('label')].find(label => label.textContent?.includes('Explain selections automatically'))!.querySelector('input')!.checked).toBe(false);
+ const next = document.querySelector<HTMLSelectElement>('#cbm-chat-model')!;
+ await act(async () => { next.value = first.id; next.dispatchEvent(new Event('change', { bubbles: true })); });
+ expect(field('cbm-chat-output-tokens')?.value).toBe('256');
+ });
+
+ it('applies the limits to the manual chat budget and the output tokens it asks for', async () => {
+ const { props, runtime } = fixture(); await render(props); await models();
+ await setLimit('cbm-chat-output-tokens', 128); await setLimit('cbm-chat-input-tokens', 1024);
+ await click('Download & load');
+ runtime.countTokens.mockResolvedValueOnce(1500);
+ await type('Explain'); await click('Send ↑');
+ expect(runtime.chat).not.toHaveBeenCalled();
+ expect(container.textContent).toMatch(/the local working limit is 1\D?024\./);
+ await click('Send ↑');
+ expect(runtime.chat).toHaveBeenCalledOnce();
+ expect(runtime.chat.mock.calls[0][2]).toMatchObject({ maxOutputTokens: 128 });
+ });
+
+ it('bounds automatic explanations by the configured output limit', async () => {
+ vi.useFakeTimers(); const { props, runtime } = fixture();
+ await render({ ...props, proactive: true, readerContext: reader('const value = 1;') }); await models();
+ await setLimit('cbm-chat-output-tokens', 64);
+ await click('Download & load');
+ await act(async () => { await vi.advanceTimersByTimeAsync(650); });
+ expect(runtime.chat.mock.calls[0][2]).toMatchObject({ maxOutputTokens: 64, generationProfile: 'automatic-explanation' });
+ });
+});
diff --git a/graph-ui/src/browser-ai/BrowserChatDock.tsx b/graph-ui/src/browser-ai/BrowserChatDock.tsx
index b852d0e39..ce0a1ee83 100644
--- a/graph-ui/src/browser-ai/BrowserChatDock.tsx
+++ b/graph-ui/src/browser-ai/BrowserChatDock.tsx
@@ -5,8 +5,9 @@ import { BROWSER_MODELS, removeBrowserModelCache } from './model-policy';
import { buildChatMessages, selectionLocation, snapshotAttachment, snapshotReaderContext, trimChatHistory, type BrowserChatAttachment, type BrowserChatContext, type BrowserChatReaderContext, type BrowserChatTurn } from './chat-model';
import { explanationInput, EXPLANATION_DELAY_MS, type ExplanationInput } from './proactive-selection';
import { prepareExplanationContext, type PreparedExplanationContext } from './explanation-context';
-import { AUTO_INPUT_TOKENS, AUTO_OUTPUT_TOKENS, CHAT_INPUT_TOKENS, citedInterpretation, parseExplanationResponse, explanationMessages, formatExplanationEvidence } from './explanation-response';
+import { AUTO_INPUT_TOKENS, AUTO_OUTPUT_TOKENS, citedInterpretation, parseExplanationResponse, explanationMessages, formatExplanationEvidence } from './explanation-response';
import { relationshipAnswer } from './relationship-answer';
+import { clampTokenLimits, tokenLimitBounds, tokenLimitsFor, useAgentPreferences } from './agent-preferences';
import { browserChatText } from './strings';
import { isGpuRuntimeFailure, BrowserRuntimeFatalError } from './runtime-fault';
import ChatMarkdown from './ChatMarkdown';
@@ -82,13 +83,32 @@ function PacketSource({ packet, citation }: { packet: PreparedExplanationContext
</>;
}
+/** A typed limit applies on blur or Enter, clamped into the model policy. */
+function TokenLimitField({ id, label, value, min, max, onCommit }: { id: string; label: string; value: number; min: number; max: number; onCommit: (value: number) => void }): JSX.Element {
+ const [text, setText] = useState(String(value));
+ useEffect(() => { setText(String(value)); }, [value]);
+ const commit = (): void => {
+ const typed = Number.parseInt(text, 10);
+ const next = Number.isFinite(typed) ? Math.min(max, Math.max(min, typed)) : value;
+ setText(String(next));
+ if (next !== value) onCommit(next);
+ };
+ return <div className="cbm-chat-token-limit">
+ <label htmlFor={id}>{label}</label>
+ <input id={id} type="number" inputMode="numeric" min={min} max={max} step={64} value={text} aria-describedby={`${id}-range`}
+ onChange={event => setText(event.target.value)} onBlur={commit} onKeyDown={event => { if (event.key === 'Enter') { event.preventDefault(); commit(); } }} />
+ <small id={`${id}-range`}>{browserChatText.limitRange(min, max)}</small>
+ </div>;
+}
+
function ContextSnapshot({ context }: { context: BrowserChatContext }): JSX.Element {
return <details className="cbm-chat-attachment"><summary>{context.label}</summary><pre>{context.text}</pre></details>;
}
/** Keep mounted when collapsed: state and worker lifetime are independent of visibility. */
export default function BrowserChatDock({ proactiveSelection, selectionScope = "", historyKey, proactive = true, onAgentStateChange, onAgentModelChange, settingsRequest = 0, open, onClose, showCollapsed = false, onOpen, attachment, readerContext, context = [], pendingContext, onContextConsumed, onContextRemoved, onAttachmentConsumed, onAttachmentRemoved, createRuntime = createBrowserChatRuntime, removeCache = removeBrowserModelCache }: BrowserChatDockProps): JSX.Element {
- const [automatic, setAutomatic] = useState(true);
+ const { preferences, setPreferences } = useAgentPreferences();
+ const automatic = preferences.automatic;
const [explanation, setExplanation] = useState<Explanation>();
const explanations = useRef(new Map<string, Explanation>());
const [retryExplanation, setRetryExplanation] = useState(0);
@@ -102,8 +122,12 @@ export default function BrowserChatDock({ proactiveSelection, selectionScope = "
const selected = useMemo(() => explanationInput(selectionScope, readerContext, proactiveSelection), [selectionScope, readerContext, proactiveSelection]);
const selectionRef = useRef(selected); selectionRef.current = selected;
const settingsSeen = useRef(settingsRequest);
- const [modelId, setModelId] = useState(initialModel.id);
+ const modelId = preferences.modelId;
const model = BROWSER_MODELS.find(candidate => candidate.id === modelId) ?? initialModel;
+ const limits = tokenLimitsFor(preferences, model);
+ // Short automatic explanations never exceed the configured limits either.
+ const autoOutput = Math.min(AUTO_OUTPUT_TOKENS, limits.outputTokens);
+ const autoInput = Math.min(AUTO_INPUT_TOKENS, limits.inputTokens, model.contextTokens - autoOutput);
const [phase, setPhase] = useState<Phase>('off');
const { draft, setDraft, turns, setTurns, ready: historyReady, historyNotice, clearHistory } = useChatHistory<ChatTurn>(historyKey);
const [error, setError] = useState<string>();
@@ -214,13 +238,13 @@ export default function BrowserChatDock({ proactiveSelection, selectionScope = "
let request = explanationMessages(packet);
let count = await currentRuntime.countTokens(request);
if (!valid()) return;
- for (let budget = 1900; count > Math.min(AUTO_INPUT_TOKENS, model.contextTokens - AUTO_OUTPUT_TOKENS) && budget >= 300; budget = Math.floor(budget * .6)) {
+ for (let budget = 1900; count > autoInput && budget >= 300; budget = Math.floor(budget * .6)) {
packet = prepareExplanationContext(snapshot.reader, snapshot.graph, budget);
request = explanationMessages(packet);
count = await currentRuntime.countTokens(request);
if (!valid()) return;
}
- if (!packet.evidence.length || count > Math.min(AUTO_INPUT_TOKENS, model.contextTokens - AUTO_OUTPUT_TOKENS)) {
+ if (!packet.evidence.length || count > autoInput) {
setExplanation({ key: snapshot.key, label: snapshot.label, answer: '', status: 'error', packet, error: !packet.evidence.length ? 'No source or graph evidence is available for this selection.' : 'This selection is too large for the local agent. Select a smaller code range and try again.' });
return;
}
@@ -228,7 +252,7 @@ export default function BrowserChatDock({ proactiveSelection, selectionScope = "
setPhase('generating');
// Keep an explanation together and ignore output from superseded selections.
let shortened = false;
- const answer = await currentRuntime.chat(request, () => {}, { maxOutputTokens: AUTO_OUTPUT_TOKENS, generationProfile: 'automatic-explanation',
+ const answer = await currentRuntime.chat(request, () => {}, { maxOutputTokens: autoOutput, generationProfile: 'automatic-explanation',
onComplete: ({ stopReason }) => { shortened = stopReason === 'length'; } });
if (valid()) {
const result = parseExplanationResponse(answer, packet);
@@ -376,7 +400,7 @@ export default function BrowserChatDock({ proactiveSelection, selectionScope = "
try {
let count = await currentRuntime.countTokens(request);
if (epoch.current !== ticket || stopRequested.current) return;
- const limit = Math.min(CHAT_INPUT_TOKENS, model.contextTokens - model.maxOutputTokens);
+ const limit = Math.min(limits.inputTokens, model.contextTokens - limits.outputTokens);
// Earlier turns give way first, oldest first; the question and its evidence stay.
while (!retry && count > limit && history.length) {
const characters = request.reduce((sum, message) => sum + message.content.length, 0);
@@ -406,7 +430,7 @@ export default function BrowserChatDock({ proactiveSelection, selectionScope = "
const output = await currentRuntime.chat(request, chunk => {
if (epoch.current !== ticket || stopRequested.current) return;
setTurns(previous => previous.map(item => item.id === id ? { ...item, answer: item.answer + chunk } : item));
- }, { onComplete: ({ stopReason }) => { shortened = stopReason === 'length'; } });
+ }, { maxOutputTokens: limits.outputTokens, onComplete: ({ stopReason }) => { shortened = stopReason === 'length'; } });
if (epoch.current !== ticket) return;
setTurns(previous => previous.map(item => item.id === id ? { ...item, answer: stopRequested.current ? item.answer : output, status: stopRequested.current ? 'stopped' : 'complete',
...shortened && !stopRequested.current ? { shortened } : {} } : item));
@@ -449,14 +473,22 @@ export default function BrowserChatDock({ proactiveSelection, selectionScope = "
return <>
{settingsOpen && <AgentSettingsDialog onClose={() => setSettingsOpen(false)}>
<section id="cbm-chat-model-settings" className="cbm-chat-settings" aria-label="Local model settings">
- {proactive && <label><input type="checkbox" checked={automatic} onChange={event => setAutomatic(event.target.checked)} /> Explain selections automatically</label>}
+ {proactive && <label><input type="checkbox" checked={automatic} onChange={event => setPreferences({ automatic: event.target.checked })} /> Explain selections automatically</label>}
<span className="cbm-chat-status" role="status">{status}</span>
<label htmlFor="cbm-chat-model">Model</label>
- <select id="cbm-chat-model" value={modelId} disabled={busy} onChange={event => { release(); explanations.current.clear(); setModelId(event.target.value); setError(undefined); setNotice(undefined); }}>
+ <select id="cbm-chat-model" value={modelId} disabled={busy} onChange={event => { release(); explanations.current.clear(); setPreferences({ modelId: event.target.value }); setError(undefined); setNotice(undefined); }}>
{BROWSER_MODELS.map(candidate => <option key={candidate.id} value={candidate.id}>{candidate.displayName} · {candidate.availability === 'unsupported' ? 'Requires runtime support' : candidate.id === model.id && phase === 'ready' ? 'Loaded' : downloaded.has(candidate.id) ? 'Downloaded this session' : 'Available'}</option>)}
</select>
<p>{sizeLabel(model.bytes)} download · {model.license}. Memory use is higher.</p>
{model.compatibilityNote && <p>{model.compatibilityNote}</p>}
+ <fieldset className="cbm-chat-token-limits">
+ <legend>{browserChatText.tokenLimits(model.displayName)}</legend>
+ <TokenLimitField id="cbm-chat-input-tokens" label={browserChatText.inputLimit} value={limits.inputTokens} {...tokenLimitBounds(model, limits.outputTokens).input}
+ onCommit={inputTokens => setPreferences(current => ({ limits: { ...current.limits, [model.id]: clampTokenLimits(model, limits, { inputTokens }) } }))} />
+ <TokenLimitField id="cbm-chat-output-tokens" label={browserChatText.outputLimit} value={limits.outputTokens} {...tokenLimitBounds(model, limits.outputTokens).output}
+ onCommit={outputTokens => setPreferences(current => ({ limits: { ...current.limits, [model.id]: clampTokenLimits(model, limits, { outputTokens }) } }))} />
+ <p>{browserChatText.limitsNote(autoInput, autoOutput)}</p>
+ </fieldset>
<p><a href={model.modelCard} target="_blank" rel="noreferrer">Model details</a> · Downloads come from Hugging Face. No model downloads automatically.</p>
<div className="cbm-chat-model-actions">
{phase === 'off' && <button type="button" className="cbm-chat-primary" disabled={model.availability !== 'available'} onClick={() => { void prepare(); }}>{runtimeFailed ? 'Reload model' : downloaded.has(model.id) ? 'Load model' : 'Download & load'}</button>}
diff --git a/graph-ui/src/browser-ai/agent-preferences.test.ts b/graph-ui/src/browser-ai/agent-preferences.test.ts
new file mode 100644
index 000000000..a890261b8
--- /dev/null
+++ b/graph-ui/src/browser-ai/agent-preferences.test.ts
@@ -0,0 +1,54 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it } from 'vitest';
+import {
+ AGENT_PREFERENCES_KEY, clampTokenLimits, DEFAULT_AGENT_PREFERENCES, defaultTokenLimits, MIN_INPUT_TOKENS, MIN_OUTPUT_TOKENS,
+ readAgentPreferences, setAgentPreferences, tokenLimitBounds, tokenLimitsFor,
+} from './agent-preferences';
+import { BROWSER_MODELS } from './model-policy';
+
+const [first, second] = BROWSER_MODELS;
+const store = (preferences: unknown, version = 1) => window.localStorage.setItem(AGENT_PREFERENCES_KEY, JSON.stringify({ version, preferences }));
+beforeEach(() => window.localStorage.clear());
+
+describe('browser-local agent preferences', () => {
+ it('defaults to the first available model, automatic explanations and the policy limits', () => {
+ expect(readAgentPreferences()).toEqual(DEFAULT_AGENT_PREFERENCES);
+ expect(DEFAULT_AGENT_PREFERENCES.modelId).toBe(first.id);
+ expect(tokenLimitsFor(readAgentPreferences(), first)).toEqual({ inputTokens: 2048, outputTokens: first.maxOutputTokens });
+ expect(tokenLimitBounds(first, 512)).toEqual({ input: { min: MIN_INPUT_TOKENS, max: first.contextTokens - 512 }, output: { min: MIN_OUTPUT_TOKENS, max: first.maxOutputTokens } });
+ });
+
+ it('restores a saved model, automatic flag and limits per model', () => {
+ store({ modelId: second.id, automatic: false, limits: { [second.id]: { inputTokens: 4096, outputTokens: 256 } } });
+ const restored = readAgentPreferences();
+ expect(restored).toEqual({ modelId: second.id, automatic: false, limits: { [second.id]: { inputTokens: 4096, outputTokens: 256 } } });
+ expect(readAgentPreferences()).toBe(restored);
+ expect(tokenLimitsFor(restored, second)).toEqual({ inputTokens: 4096, outputTokens: 256 });
+ expect(tokenLimitsFor(restored, first)).toEqual(defaultTokenLimits(first));
+ });
+
+ it('rejects malformed data, unknown versions, unknown models and limits outside the model policy', () => {
+ window.localStorage.setItem(AGENT_PREFERENCES_KEY, '{bad json');
+ expect(readAgentPreferences()).toEqual(DEFAULT_AGENT_PREFERENCES);
+ store({ modelId: second.id }, 2);
+ expect(readAgentPreferences()).toEqual(DEFAULT_AGENT_PREFERENCES);
+ store({ modelId: 'someone/else', automatic: 'no', limits: {
+ [first.id]: { inputTokens: first.contextTokens, outputTokens: 512 },
+ [second.id]: { inputTokens: 2048, outputTokens: second.maxOutputTokens + 1 },
+ 'someone/else': { inputTokens: 1024, outputTokens: 64 },
+ } });
+ expect(readAgentPreferences()).toEqual(DEFAULT_AGENT_PREFERENCES);
+ store({ limits: { [first.id]: { inputTokens: 1024.5, outputTokens: 64 }, [second.id]: { inputTokens: 1024, outputTokens: 64 } } });
+ expect(readAgentPreferences().limits).toEqual({ [second.id]: { inputTokens: 1024, outputTokens: 64 } });
+ });
+
+ it('saves a versioned record and clamps requested limits into the model policy', () => {
+ const limits = clampTokenLimits(first, defaultTokenLimits(first), { inputTokens: 99_999, outputTokens: 1 });
+ expect(limits).toEqual({ inputTokens: first.contextTokens - MIN_OUTPUT_TOKENS, outputTokens: MIN_OUTPUT_TOKENS });
+ expect(clampTokenLimits(first, limits, { outputTokens: 512 })).toEqual({ inputTokens: first.contextTokens - 512, outputTokens: 512 });
+ setAgentPreferences({ automatic: false, limits: { [first.id]: limits } });
+ expect(JSON.parse(window.localStorage.getItem(AGENT_PREFERENCES_KEY)!)).toEqual({ version: 1,
+ preferences: { modelId: first.id, automatic: false, limits: { [first.id]: limits } } });
+ expect(readAgentPreferences()).toMatchObject({ automatic: false, limits: { [first.id]: limits } });
+ });
+});
diff --git a/graph-ui/src/browser-ai/agent-preferences.ts b/graph-ui/src/browser-ai/agent-preferences.ts
new file mode 100644
index 000000000..cb231db9b
--- /dev/null
+++ b/graph-ui/src/browser-ai/agent-preferences.ts
@@ -0,0 +1,107 @@
+import { useCallback, useSyncExternalStore } from 'react';
+import { CHAT_INPUT_TOKENS } from './explanation-response';
+import { BROWSER_MODELS, type BrowserModel } from './model-policy';
+
+/** Below these the local agent cannot hold a question with its evidence or a sentence of answer. */
+export const MIN_INPUT_TOKENS = 512;
+export const MIN_OUTPUT_TOKENS = 32;
+
+export interface TokenLimits { inputTokens: number; outputTokens: number }
+export interface AgentPreferences {
+ modelId: string;
+ automatic: boolean;
+ /** Only models whose limits were changed; every other model uses its defaults. */
+ limits: Readonly<Record<string, TokenLimits>>;
+}
+
+const AVAILABLE = BROWSER_MODELS.filter(model => model.availability === 'available');
+export const DEFAULT_AGENT_PREFERENCES: Readonly<AgentPreferences> = Object.freeze({ modelId: AVAILABLE[0].id, automatic: true, limits: Object.freeze({}) });
+export const AGENT_PREFERENCES_KEY = 'cbm-agent-preferences-v1';
+const CHANGE = 'cbm-agent-preferences-change';
+
+/** The model policy bounds both limits: the answer stays within the model's output
+ * ceiling and the question plus the answer within its browser context. */
+export function tokenLimitBounds(model: BrowserModel, outputTokens: number) {
+ return { input: { min: MIN_INPUT_TOKENS, max: model.contextTokens - outputTokens }, output: { min: MIN_OUTPUT_TOKENS, max: model.maxOutputTokens } };
+}
+
+export function defaultTokenLimits(model: BrowserModel): TokenLimits {
+ return { inputTokens: Math.min(CHAT_INPUT_TOKENS, model.contextTokens - model.maxOutputTokens), outputTokens: model.maxOutputTokens };
+}
+
+export function tokenLimitsFor(preferences: Readonly<AgentPreferences>, model: BrowserModel): TokenLimits {
+ return preferences.limits[model.id] ?? defaultTokenLimits(model);
+}
+
+/** Clamp a requested change into the policy, so a saved value is always one validation accepts. */
+export function clampTokenLimits(model: BrowserModel, current: TokenLimits, change: Partial<TokenLimits>): TokenLimits {
+ const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, Math.round(value)));
+ const outputTokens = clamp(change.outputTokens ?? current.outputTokens, MIN_OUTPUT_TOKENS, model.maxOutputTokens);
+ return { outputTokens, inputTokens: clamp(change.inputTokens ?? current.inputTokens, MIN_INPUT_TOKENS, model.contextTokens - outputTokens) };
+}
+
+const record = (value: unknown): Record<string, unknown> | undefined => typeof value === 'object' && value !== null && !Array.isArray(value)
+ ? value as Record<string, unknown> : undefined;
+const within = (value: unknown, min: number, max: number): value is number => Number.isSafeInteger(value) && (value as number) >= min && (value as number) <= max;
+
+function validated(value: unknown): Readonly<AgentPreferences> {
+ const row = record(value) ?? {};
+ const limits: Record<string, TokenLimits> = {};
+ for (const model of BROWSER_MODELS) {
+ const stored = record(record(row.limits)?.[model.id]);
+ if (!stored || !within(stored.outputTokens, MIN_OUTPUT_TOKENS, model.maxOutputTokens)) continue;
+ if (within(stored.inputTokens, MIN_INPUT_TOKENS, model.contextTokens - stored.outputTokens)) {
+ limits[model.id] = Object.freeze({ inputTokens: stored.inputTokens, outputTokens: stored.outputTokens });
+ }
+ }
+ return Object.freeze({
+ modelId: BROWSER_MODELS.some(model => model.id === row.modelId) ? row.modelId as string : DEFAULT_AGENT_PREFERENCES.modelId,
+ automatic: typeof row.automatic === 'boolean' ? row.automatic : DEFAULT_AGENT_PREFERENCES.automatic,
+ limits: Object.freeze(limits),
+ });
+}
+
+function decode(raw: string | null): Readonly<AgentPreferences> {
+ try {
+ const stored = record(JSON.parse(raw ?? 'null'));
+ if (stored?.version === 1) return validated(stored.preferences);
+ } catch { /* Invalid storage is equivalent to no saved preference. */ }
+ return DEFAULT_AGENT_PREFERENCES;
+}
+
+let snapshot: { raw: string | null; value: Readonly<AgentPreferences>; sessionOnly: boolean } | undefined;
+
+/** Stable snapshots: an unchanged store returns the same object. */
+export function readAgentPreferences(): Readonly<AgentPreferences> {
+ if (snapshot?.sessionOnly) return snapshot.value;
+ let raw: string | null;
+ try { raw = window.localStorage.getItem(AGENT_PREFERENCES_KEY); }
+ catch { return snapshot?.value ?? DEFAULT_AGENT_PREFERENCES; }
+ if (snapshot?.raw === raw) return snapshot.value;
+ snapshot = { raw, value: decode(raw), sessionOnly: false };
+ return snapshot.value;
+}
+
+export function setAgentPreferences(update: Partial<AgentPreferences> | ((current: Readonly<AgentPreferences>) => Partial<AgentPreferences>)): void {
+ const current = readAgentPreferences();
+ const value = validated({ ...current, ...(typeof update === 'function' ? update(current) : update) });
+ if (JSON.stringify(value) === JSON.stringify(current)) return;
+ const raw = JSON.stringify({ version: 1, preferences: value });
+ let sessionOnly = false;
+ try { window.localStorage.setItem(AGENT_PREFERENCES_KEY, raw); }
+ catch { sessionOnly = true; }
+ snapshot = { raw, value, sessionOnly };
+ window.dispatchEvent(new CustomEvent(CHANGE));
+}
+
+/** Browser-local: the chosen model, automatic explanations and token limits per model. */
+export function useAgentPreferences(): { preferences: Readonly<AgentPreferences>; setPreferences: typeof setAgentPreferences } {
+ const subscribe = useCallback((listener: () => void) => {
+ const stored = (event: StorageEvent) => { if (event.key === null || event.key === AGENT_PREFERENCES_KEY) listener(); };
+ window.addEventListener(CHANGE, listener);
+ window.addEventListener('storage', stored);
+ return () => { window.removeEventListener(CHANGE, listener); window.removeEventListener('storage', stored); };
+ }, []);
+ const preferences = useSyncExternalStore(subscribe, readAgentPreferences, () => DEFAULT_AGENT_PREFERENCES);
+ return { preferences, setPreferences: setAgentPreferences };
+}
diff --git a/graph-ui/src/browser-ai/agent-settings.css b/graph-ui/src/browser-ai/agent-settings.css
index 14da7035b..34a6ce6e9 100644
--- a/graph-ui/src/browser-ai/agent-settings.css
+++ b/graph-ui/src/browser-ai/agent-settings.css
@@ -26,3 +26,9 @@
.cbm-agent-settings .cbm-chat-status { color: var(--chat-muted); font-size: 12px; }
.cbm-agent-settings .cbm-chat-loading { padding: 0; }
.cbm-agent-settings .cbm-chat-error, .cbm-agent-settings .cbm-chat-notice { margin: 0 !important; }
+.cbm-agent-settings .cbm-chat-token-limits { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 10px 16px; margin: 0; padding: 12px; border: 1px solid var(--chat-border); border-radius: 9px; }
+.cbm-agent-settings .cbm-chat-token-limits legend { padding: 0 6px; font-size: 12px; font-weight: 500; }
+.cbm-agent-settings .cbm-chat-token-limits p { grid-column: 1 / -1; }
+.cbm-agent-settings .cbm-chat-token-limit { display: grid; gap: 4px; }
+.cbm-agent-settings .cbm-chat-token-limit input { width: 100%; font: inherit; color: inherit; border: 1px solid var(--chat-border); background: #0d1612; border-radius: 7px; padding: 7px 10px; }
+.cbm-agent-settings .cbm-chat-token-limit small { color: var(--chat-muted); font-size: 11px; }
diff --git a/graph-ui/src/browser-ai/strings.ts b/graph-ui/src/browser-ai/strings.ts
index 2bc44d5b4..eb0afe296 100644
--- a/graph-ui/src/browser-ai/strings.ts
+++ b/graph-ui/src/browser-ai/strings.ts
@@ -117,4 +117,9 @@ export const browserChatText = {
historyTrimmed: (count: number) => `${count} earlier ${count === 1 ? 'message was' : 'messages were'} left out to fit the input limit.`,
waitingForScope: 'Waiting for the complete scope before explaining…',
partialScope: 'This scope did not load completely, so it is not explained automatically.',
+ tokenLimits: (model: string) => `Token limits for ${model}`,
+ inputLimit: 'Input (context)',
+ outputLimit: 'Output (answer)',
+ limitRange: (min: number, max: number) => `${min.toLocaleString('en-US')} to ${max.toLocaleString('en-US')} tokens`,
+ limitsNote: (input: number, output: number) => `Stored in this browser for each model. Automatic explanations use at most ${input.toLocaleString('en-US')} input and ${output.toLocaleString('en-US')} output tokens.`,
};