smart-limits

1// The entry point of the hooks module: the engine loads this file, and the
2// files beside it hold the handlers, each reaching the engine through the
3// `$` it is handed. The logic they feed lives in src/ as plain functions
4// with tests. The settings arrive as `options`; a change to them reloads
5// the module.
6
7import type {Register} from 'claude-code';
8
9import {registerCommands} from './commands.ts';
10import {onSessionCompact, onTurnComplete} from './compaction.ts';
11import {registerLimitGuards} from './limits.ts';
12import {registerMeasureHook} from './measure.ts';
13import {startSession} from './start.ts';
14import {configure} from './state.ts';
15import {registerToolHooks} from './tools.ts';
16
17export const register: Register = (on, options) => {
18  configure(options);
19
20  on('session.start', async ($, event, next) => {
21    await startSession($, event);
22    return await next(event);
23  });
24
25  on('turn.complete', async ($, event, next) => {
26    onTurnComplete($, event);
27    return await next(event);
28  });
29
30  on('session.compact', async ($, event, next) => {
31    await onSessionCompact($, event);
32    return await next(event);
33  }).catch(async (error, event, next) => await next(event));
34
35  registerMeasureHook(on);
36  registerLimitGuards(on);
37  registerToolHooks(on);
38  registerCommands(on);
39};
40

1// /smart-limits:status, answered in code; the markdown body in commands/
2// runs only when the module is not loaded.
3
4import type {EngineInterface, On} from 'claude-code';
5
6import {statusText} from '../src/status.ts';
7import {liveWindows} from '../src/windows.ts';
8
9import {reevaluate} from './limits.ts';
10import {isReminding, state} from './state.ts';
11
12async function status($: EngineInterface): Promise<string> {
13  await reevaluate($);
14  const now = await $.clock.now();
15  return statusText({
16    now,
17    compactPending: state.compactPending,
18    context: state.context,
19    hard: state.hard,
20    isReminding: isReminding(),
21    lastCompact: state.lastCompact,
22    lastEngineCompact: state.lastEngineCompact,
23    request: state.request,
24    settings: state.settings,
25    soft: state.soft,
26    windows: liveWindows(state.windows, now)
27  });
28}
29
30export function registerCommands(on: On): void {
31  on('command.run', {command: 'smart-limits:status'}, async $ => ({text: await status($)}))
32    .catch(async (error, event, next) => (next.called ?
33      await next(event) :
34      {text: `the status command failed (${next.error.kind}); see the debug log`}));
35}
36

1// The context window: the model asks for the compaction through the
2// plugin's tool, at a point of its own choosing; the engine refuses a
3// compaction while a turn runs, so the request waits for the end of the
4// main turn and is made from a timer a second later, a few times at most.
5// Once the conversation is compacted, a prompt wakes the model to go on.
6// The engine's own compactions are observed and never cancelled, and a
7// subagent's transcript is never touched.
8
9import type {
10  EngineInterface, SessionCompactInput, SessionCompactResult, SessionMeasureInput, TurnCompleteInput
11} from 'claude-code';
12
13import {CompactAction, compactAction, joinInstructions, WAKE_TEXT} from '../src/compaction.ts';
14import {percentText} from '../src/windows.ts';
15
16import {armCompaction, keep, noteCompaction, noteCompactRefused, state} from './state.ts';
17
18const RETRY_MS = 1000;
19const WAKE_MS = 1000;
20
21// The engine's answer, or nothing when it refused the call: a turn runs, or
22// the session is headless, where the engine compacts inside a turn only.
23async function compactOrRefused(
24  $: EngineInterface,
25  instructions: string | undefined
26): Promise<SessionCompactResult | undefined> {
27  try {
28    return await $.session.compact(instructions === undefined ? {} : {instructions});
29  } catch (error) {
30    $.ui.log(`the compaction was refused: ${String(error)}`, {to: 'debug'});
31    return undefined;
32  }
33}
34
35async function wake($: EngineInterface): Promise<void> {
36  try {
37    await $.prompt.submit({text: WAKE_TEXT});
38  } catch (error) {
39    $.ui.log(`the model was not woken after the compaction: ${String(error)}`, {to: 'transcript'});
40  }
41}
42
43export async function attemptCompact($: EngineInterface): Promise<void> {
44  const {request, settings} = state;
45  if (request === undefined) {
46    return;
47  }
48
49  const percent = state.context?.percent;
50  const result = await compactOrRefused($, joinInstructions(request.instructions ?? '', settings.compactInstructions));
51  const at = await $.clock.now();
52  if (result === undefined) {
53    noteCompactRefused();
54    void keep($);
55    $.ui.log(state.compactPending ?
56      'the requested compaction is tried again after the next main turn' :
57      'the request is dropped; the engine compacts on its own at its threshold', {to: 'debug'});
58    return;
59  }
60
61  noteCompaction({
62    at,
63    skip: result.skip
64  });
65  void keep($);
66  const fill = percent === undefined ? '' : ` at ${percentText(percent)} of the context window`;
67  $.ui.log(result.skip === undefined ?
68    `compacted the conversation${fill} at the model's request` :
69    `the compaction${fill} the model asked for was skipped: ${result.skip}`, {to: 'transcript'});
70  $.clock.after(WAKE_MS, () => {
71    void wake($);
72  });
73}
74
75export function onMeasureForCompaction($: EngineInterface, event: SessionMeasureInput): void {
76  state.context = event.context;
77  if (compactAction(event.context.percent, state.settings.compactAt, state.compactArmed) !== CompactAction.Rearm) {
78    return;
79  }
80
81  armCompaction();
82  void keep($);
83}
84
85export function onTurnComplete($: EngineInterface, event: TurnCompleteInput): void {
86  if (event.agentId !== undefined || !state.compactPending) {
87    return;
88  }
89
90  $.clock.after(RETRY_MS, () => {
91    void attemptCompact($);
92  });
93}
94
95// The engine's own compactions of the main conversation, for the status
96// command: the person's /compact and the threshold's. A precompute installs
97// nothing, and the plugin's own is recorded from its call.
98export async function onSessionCompact($: EngineInterface, event: SessionCompactInput): Promise<void> {
99  if (event.agentId === undefined && (event.trigger === 'auto' || event.trigger === 'manual')) {
100    state.lastEngineCompact = {
101      at: await $.clock.now(),
102      trigger: event.trigger
103    };
104  }
105}
106

1// The subscription windows: the status line while there is a reading, one
2// warning per crossing of the soft limit, and at the hard limit the command
3// the settings name plus the refusal of Bash, Write, Edit, NotebookEdit and
4// new agents in every loop, until the share falls below the limit or the
5// window resets. A timer at the nearest reset reads the engine's figures
6// again, since no measurement arrives while the session is idle; once no
7// window holds the hard limit, the command named for that moment runs, so
8// that a run paused at the limit goes on.
9
10import type {EngineInterface, On, SessionRateLimit} from 'claude-code';
11
12import type {Command} from '../src/options.ts';
13
14import {
15  clearedText, crossingsOf, denyText, entered, liveWindows, nextResetAt, peakWindow, softText, statusLine, windowByKey,
16  windowsAbove
17} from '../src/windows.ts';
18
19import {keep, state} from './state.ts';
20
21// A command runs from a timer: inside a hook the turn waits on, the engine
22// refuses it.
23const COMMAND_DELAY_MS = 1000;
24// Past the reset by this much, so the window is over by the engine's clock too.
25const RESET_GRACE_MS = 2000;
26// A timer longer than this re-arms when it fires: the host's timers cannot
27// wait longer than about 24 days, and a spend limit may reset later than that.
28const MAX_WAIT_MS = 24 * 60 * 60 * 1000;
29const SOFT_TOAST_MS = 20_000;
30// What the model reads carries the plugin's name; a transcript line does
31// not, since the engine prints it under the name already.
32const PREFIX = 'smart-limits: ';
33const GUARD_FAILED = `${PREFIX}the guard failed while a subscription window is past the hard limit; see the ` +
34  'debug log and /smart-limits:status';
35
36function firstLine(text: string | undefined): string {
37  return text === undefined ? '' : `: ${text.split('\n', 1)[0] ?? ''}`;
38}
39
40async function runCommand($: EngineInterface, command: Command, when: string): Promise<void> {
41  try {
42    const result = await $.command.run({
43      args: command.args,
44      command: command.command
45    });
46    $.ui.log(`/${command.command} ran ${when}${firstLine(result.text)}`, {to: 'debug'});
47  } catch (error) {
48    $.ui.log(`/${command.command} did not run ${when}: ${String(error)}`, {to: 'transcript'});
49  }
50}
51
52function runLater($: EngineInterface, command: Command | undefined, when: string): void {
53  if (command === undefined) {
54    return;
55  }
56
57  $.clock.after(COMMAND_DELAY_MS, () => {
58    void runCommand($, command, when);
59  });
60}
61
62function armResetTimer($: EngineInterface, resetsAt: number | undefined, now: number): void {
63  state.resetTimer?.cancel();
64  state.resetTimer = undefined;
65  if (resetsAt === undefined) {
66    return;
67  }
68
69  const wait = Math.min(MAX_WAIT_MS, Math.max(0, resetsAt - now) + RESET_GRACE_MS);
70  state.resetTimer = $.clock.after(wait, () => {
71    state.resetTimer = undefined;
72    void reevaluate($);
73  });
74}
75
76// One reading of the windows, from a measurement or from the engine's
77// figures on request: everything the plugin shows and refuses follows.
78export function applyWindows($: EngineInterface, windows: readonly SessionRateLimit[], now: number): void {
79  const {settings} = state;
80  state.windows = windows.map(window => ({...window}));
81  const live = liveWindows(state.windows, now);
82  $.ui.status(statusLine(live, now));
83
84  const crossings = crossingsOf(live, settings);
85  const newSoft = entered(state.soft, crossings.soft);
86  const newHard = entered(state.hard, crossings.hard);
87  const isChanged = newSoft.length > 0 || newHard.length > 0 || state.soft.length !== crossings.soft.length ||
88    state.hard.length !== crossings.hard.length;
89  const previousHard = state.hard;
90  state.soft = crossings.soft;
91  state.hard = crossings.hard;
92  if (isChanged) {
93    void keep($);
94  }
95
96  if (previousHard.length > 0 && crossings.hard.length === 0) {
97    $.ui.log(clearedText(previousHard, live), {to: 'transcript'});
98    runLater($, settings.atReset, 'after the hard limit cleared');
99  }
100
101  for (const key of newSoft) {
102    const window = windowByKey(live, key);
103    if (window !== undefined) {
104      $.ui.toast(softText(window, settings.limitSoft, now), {timeoutMs: SOFT_TOAST_MS});
105    }
106  }
107
108  const peak = peakWindow(windowsAbove(live, settings.limitHard));
109  state.denyText = peak === undefined ? undefined : denyText(peak, settings.limitHard, now);
110  if (peak !== undefined && newHard.length > 0) {
111    $.ui.log(state.denyText ?? '', {to: 'transcript'});
112    runLater($, settings.atHard, 'at the hard limit');
113  }
114
115  armResetTimer($, nextResetAt(live, now), now);
116}
117
118export async function reevaluate($: EngineInterface): Promise<void> {
119  try {
120    const usage = await $.session.usage();
121    const now = await $.clock.now();
122    state.context = usage.context;
123    applyWindows($, usage.rateLimits, now);
124  } catch (error) {
125    $.ui.log(`reading the usage failed: ${String(error)}`, {to: 'debug'});
126  }
127}
128
129// The guards judge on the last reading applied. The response that brings a
130// reading past the limit may carry tool uses too, and the engine dispatches
131// those calls before the measurement reaches the plugin and before its own
132// figures move: they run, and the next response's calls are refused.
133export function registerLimitGuards(on: On): void {
134  on('tool.call', {tool: ['Bash', 'Write', 'Edit', 'NotebookEdit']}, async ($, event, next) => (
135    state.denyText === undefined ? await next(event) : {deny: `${PREFIX}${state.denyText}`}
136  )).catch(async (error, event, next) => {
137    if (next.called) {
138      return await next(event);
139    }
140
141    return state.denyText === undefined ? await next(event) : {deny: GUARD_FAILED};
142  });
143
144  on('agent.spawn', async ($, event, next) => (
145    state.denyText === undefined ? await next(event) : {deny: `${PREFIX}${state.denyText}`}
146  )).catch(async (error, event, next) => {
147    if (next.called) {
148      return await next(event);
149    }
150
151    return state.denyText === undefined ? await next(event) : {deny: GUARD_FAILED};
152  });
153}
154

1// The one session.measure hook of the module: the windows first, the
2// context after, each part on its own so that one that fails leaves the
3// other running. The hook observes; its answer changes nothing.
4
5import type {EngineInterface, On} from 'claude-code';
6
7import {onMeasureForCompaction} from './compaction.ts';
8import {applyWindows} from './limits.ts';
9
10async function part($: EngineInterface, name: string, run: () => Promise<void> | void): Promise<void> {
11  try {
12    await run();
13  } catch (error) {
14    $.ui.log(`the ${name} part of session.measure failed: ${String(error)}`, {to: 'debug'});
15  }
16}
17
18export function registerMeasureHook(on: On): void {
19  on('session.measure', async ($, event, next) => {
20    const now = await $.clock.now();
21    $.ui.log(`measured: context ${event.context.percent === undefined ? 'unknown' : `${event.context.percent}%`} (${
22      event.context.tokens ?? '?'} of ${event.context.window}), windows ${
23      event.rateLimits.map(window => `${window.kind} ${window.percentUsed}%`).join(', ') || 'none'}; changed: ${
24      event.changed.join(', ')}`, {to: 'debug'});
25    await part($, 'windows', () => {
26      applyWindows($, event.rateLimits, now);
27    });
28    await part($, 'context', () => {
29      onMeasureForCompaction($, event);
30    });
31    return await next(event);
32  });
33}
34

1// The start of a session: the figures the engine already has (empty off a
2// subscription and before the first response), the settings in force as one
3// line in the debug log for whoever checks where the values came from, and
4// a line in the transcript for each setting set aside.
5
6import type {EngineInterface, SessionStartInput} from 'claude-code';
7
8import {reevaluate} from './limits.ts';
9import {restore, settingsLine, state} from './state.ts';
10import {registerCompactTool} from './tools.ts';
11
12export async function startSession($: EngineInterface, event: SessionStartInput): Promise<void> {
13  $.ui.log(`${settingsLine()}; ${event.isInteractive ? 'interactive' : 'headless'} on ${
14    event.surface ?? 'no surface'}`, {to: 'debug'});
15  for (const note of state.settings.notes) {
16    $.ui.log(note, {to: 'transcript'});
17  }
18
19  await registerCompactTool($);
20  await restore($);
21  await reevaluate($);
22}
23

1// The state of one session, kept in the module between events: the settings
2// in force, the latest reading of the windows and the context, which
3// crossings were announced, whether the tools are refused, and what the
4// plugin knows about compactions. A reload of the module starts it over.
5
6import type {EngineInterface, PluginOptions, SessionContextUsage, Timer} from 'claude-code';
7
8import type {Compaction, CompactRequest, EngineCompaction} from '../src/status.ts';
9import type {Window} from '../src/windows.ts';
10
11import {DEFAULT_SETTINGS, parseSettings, type Settings} from '../src/options.ts';
12
13export const OWN_COMMAND_PREFIX = 'smart-limits:';
14
15// The values kept in the engine's session state across a hot reload of the
16// module (types/index.d.ts); `plugin` and `key` are literals, as `$.state`
17// asks.
18const CROSSINGS = {
19  key: 'crossings',
20  plugin: 'smart-limits'
21} as const;
22const COMPACTION = {
23  key: 'compaction',
24  plugin: 'smart-limits'
25} as const;
26
27// Refusals of one requested compaction before the plugin drops the request:
28// each from the timer after a main turn. A headless session refuses every
29// one, since its engine compacts inside a turn only.
30const MAX_COMPACT_REFUSALS = 4;
31
32export type State = {
33  // Armed while the context fill was last seen below the threshold: at or
34  // above it the model is reminded.
35  compactArmed: boolean;
36  // A requested compaction waits for the end of the main turn.
37  compactPending: boolean;
38  // The refusals of the request so far.
39  compactRefusals: number;
40  context: SessionContextUsage | undefined;
41  // The refusal the guards answer with while the hard limit is crossed.
42  denyText: string | undefined;
43  // The crossings announced so far, by crossing key.
44  hard: string[];
45  lastCompact: Compaction | undefined;
46  lastEngineCompact: EngineCompaction | undefined;
47  // The model's request, until the compaction it asked for.
48  request: CompactRequest | undefined;
49  resetTimer: Timer | undefined;
50  settings: Settings;
51  soft: string[];
52  // The windows as the engine last reported them, reset or not.
53  windows: Window[];
54};
55
56export const state: State = {
57  compactArmed: true,
58  compactPending: false,
59  compactRefusals: 0,
60  context: undefined,
61  denyText: undefined,
62  hard: [],
63  lastCompact: undefined,
64  lastEngineCompact: undefined,
65  request: undefined,
66  resetTimer: undefined,
67  settings: DEFAULT_SETTINGS,
68  soft: [],
69  windows: []
70};
71
72export function configure(options: PluginOptions): void {
73  state.settings = parseSettings(options, OWN_COMMAND_PREFIX);
74}
75
76// What the engine kept for this session, taken back at the start: after a
77// reload the crossings already acted on are not announced again, and the
78// compaction's memory stands.
79export async function restore($: EngineInterface): Promise<void> {
80  try {
81    const crossings = await $.state.get(CROSSINGS);
82    if (crossings.value !== undefined) {
83      state.soft = [...crossings.value.soft];
84      state.hard = [...crossings.value.hard];
85    }
86
87    const compaction = await $.state.get(COMPACTION);
88    if (compaction.value !== undefined) {
89      state.compactArmed = compaction.value.isArmed;
90      state.lastCompact = compaction.value.lastCompactAt === null ?
91        undefined :
92        {
93          at: compaction.value.lastCompactAt,
94          skip: compaction.value.lastCompactSkip ?? undefined
95        };
96      state.request = compaction.value.requestedAt === null ?
97        undefined :
98        {
99          at: compaction.value.requestedAt,
100          instructions: compaction.value.requestedInstructions ?? undefined
101        };
102      state.compactPending = state.request !== undefined;
103    }
104  } catch (error) {
105    $.ui.log(`the session state was not read: ${String(error)}`, {to: 'debug'});
106  }
107}
108
109export async function keep($: EngineInterface): Promise<void> {
110  try {
111    await $.state.set(CROSSINGS, {
112      hard: [...state.hard],
113      soft: [...state.soft]
114    });
115    await $.state.set(COMPACTION, {
116      isArmed: state.compactArmed,
117      lastCompactAt: state.lastCompact?.at ?? null,
118      lastCompactSkip: state.lastCompact?.skip ?? null,
119      requestedAt: state.request?.at ?? null,
120      requestedInstructions: state.request?.instructions ?? null
121    });
122  } catch (error) {
123    $.ui.log(`the session state was not written: ${String(error)}`, {to: 'debug'});
124  }
125}
126
127// The compaction's bookkeeping, in plain functions so that a handler that
128// awaits the engine does not write the state across the wait itself.
129export function armCompaction(): void {
130  state.compactArmed = true;
131  state.compactPending = false;
132  state.compactRefusals = 0;
133}
134
135export function noteRequest(request: CompactRequest): void {
136  state.request = request;
137  state.compactPending = true;
138  state.compactRefusals = 0;
139}
140
141// The compaction the model asked for is done (or skipped by the engine):
142// the request is over, and the reminders wait for a reading below the
143// threshold.
144export function noteCompaction(compaction: Compaction): void {
145  state.lastCompact = compaction;
146  state.request = undefined;
147  state.compactArmed = false;
148  state.compactPending = false;
149}
150
151// A refusal: the request stands and is tried again after the next main
152// turn, until its refusals reach the limit; then it is dropped.
153export function noteCompactRefused(): void {
154  state.compactRefusals += 1;
155  state.compactPending = state.compactRefusals < MAX_COMPACT_REFUSALS;
156  if (!state.compactPending) {
157    state.request = undefined;
158  }
159}
160
161export function isReminding(): boolean {
162  const percent = state.context?.percent;
163  return state.request === undefined && state.compactArmed && percent !== undefined && state.settings.compactAt > 0 &&
164    percent >= state.settings.compactAt;
165}
166
167function thresholdText(value: number): string {
168  return value > 0 ? `${value}%` : 'off';
169}
170
171export function settingsLine(): string {
172  const {settings} = state;
173  return `compact at ${thresholdText(settings.compactAt)}, soft ${thresholdText(settings.limitSoft)}, hard ${
174    thresholdText(settings.limitHard)}, at hard ${
175    settings.atHard === undefined ? 'none' : `/${settings.atHard.command}`}, at reset ${
176    settings.atReset === undefined ? 'none' : `/${settings.atReset.command}`}`;
177}
178

1// The plugin's tool for the model, and the reminder: while the context
2// window is past the threshold, every tool result of the main conversation
3// carries a line the model reads and the person does not, asking for a
4// compaction at a good point; the tool records the request, and the
5// compaction follows the end of the turn (hooks/compaction.ts).
6
7import type {EngineInterface, On} from 'claude-code';
8
9import {
10  COMPACT_TOOL, COMPACT_TOOL_DESCRIPTION, COMPACT_TOOL_NAME, COMPACT_TOOL_SCHEMA, reminderText, requestAnswer,
11  SUBAGENT_REFUSAL
12} from '../src/compaction.ts';
13
14import {isReminding, keep, noteRequest, state} from './state.ts';
15
16// The engine's tool table does not declare the plugin's own tool, so its name
17// is matched as a pattern and its input read as plain fields.
18const COMPACT_TOOL_PATTERN = new RegExp(`^${COMPACT_TOOL}$`, 'u');
19const TOOL_FAILED = 'smart-limits: the compact tool failed; end the turn and call it again';
20
21function instructionsOf(fields: Record<string, unknown>): string | undefined {
22  const note = typeof fields.instructions === 'string' ? fields.instructions.trim() : '';
23  return note === '' ? undefined : note;
24}
25
26export async function registerCompactTool($: EngineInterface): Promise<void> {
27  await $.tool.register({
28    description: COMPACT_TOOL_DESCRIPTION,
29    inputSchema: COMPACT_TOOL_SCHEMA,
30    isDeferred: false,
31    name: COMPACT_TOOL_NAME
32  });
33}
34
35export function registerToolHooks(on: On): void {
36  on('tool.call', {tool: COMPACT_TOOL_PATTERN}, async ($, event) => {
37    if (event.agentId !== undefined) {
38      return {deny: SUBAGENT_REFUSAL};
39    }
40
41    const {agentId, tool, tool_use_id: toolUseId, ...fields} = event;
42    noteRequest({
43      at: await $.clock.now(),
44      instructions: instructionsOf(fields)
45    });
46    void keep($);
47    return {result: requestAnswer(state.context?.percent)};
48  }).catch(async (error, event, next) => (next.called ? await next(event) : {deny: TOOL_FAILED}));
49
50  // The reminder rides on every other tool's result in the main loop.
51  on('tool.call', async ($, event, next) => {
52    const result = await next(event);
53    if (event.agentId !== undefined || COMPACT_TOOL_PATTERN.test(event.tool) || result.deny !== undefined ||
54      !isReminding()) {
55      return result;
56    }
57
58    const percent = state.context?.percent ?? 0;
59    return {
60      ...result,
61      context: [...(result.context ?? []), reminderText(percent, state.settings.compactAt)]
62    };
63  }).catch(async (error, event, next) => await next(event));
64}
65

1// The text of /smart-limits:status: the windows with their shares and
2// resets, the context fill, the thresholds, and what is in force now.
3
4import type {Command, Settings} from './options.ts';
5
6import {localTime, parseIso, waitText} from './time.ts';
7import {percentText, type Window, windowLabel} from './windows.ts';
8
9export type ContextFill = {
10  percent?: number;
11  tokens?: number;
12  window: number;
13};
14
15export type Compaction = {
16  at: number;
17  skip: string | undefined;
18};
19
20export type CompactRequest = {
21  at: number;
22  instructions: string | undefined;
23};
24
25export type EngineCompaction = {
26  at: number;
27  trigger: string;
28};
29
30export type StatusInput = {
31  compactPending: boolean;
32  context: ContextFill | undefined;
33  hard: readonly string[];
34  isReminding: boolean;
35  lastCompact: Compaction | undefined;
36  lastEngineCompact: EngineCompaction | undefined;
37  now: number;
38  request: CompactRequest | undefined;
39  settings: Settings;
40  soft: readonly string[];
41  windows: readonly Window[];
42};
43
44function windowText(window: Window, now: number): string {
45  const resetsAt = parseIso(window.resetsAt);
46  const reset = resetsAt === undefined ? '' : ` (resets ${localTime(resetsAt, now)}, ${waitText(resetsAt, now)})`;
47  return `${windowLabel(window.kind)} ${percentText(window.percentUsed)}${reset}`;
48}
49
50function thresholdText(value: number): string {
51  return value > 0 ? percentText(value) : 'off';
52}
53
54function commandText(command: Command | undefined): string {
55  return command === undefined ? 'none' : `/${command.command} ${command.args}`.trim();
56}
57
58function kindsOf(keys: readonly string[]): string {
59  return keys.map(key => windowLabel(key.split('@', 1)[0] ?? key)).join(', ');
60}
61
62function contextText(context: ContextFill | undefined): string {
63  if (context?.percent === undefined) {
64    return 'no reading (none before the first response, or right after a compaction)';
65  }
66
67  return `${percentText(context.percent)} of ${context.window} tokens${
68    context.tokens === undefined ? '' : ` (${context.tokens})`}`;
69}
70
71function inForceText(input: StatusInput): string {
72  if (input.hard.length > 0) {
73    return `hard limit crossed by ${kindsOf(input.hard)}: Bash, Write, Edit, NotebookEdit and new agents are refused`;
74  }
75
76  return input.soft.length > 0 ?
77    `soft limit crossed by ${kindsOf(input.soft)}: warned, nothing refused` :
78    'nothing crossed, nothing refused';
79}
80
81function compactionText(input: StatusInput): string {
82  const parts: string[] = [];
83  if (input.request !== undefined) {
84    parts.push(`requested by the model at ${localTime(input.request.at, input.now)}, waits for the end of the turn`);
85  } else if (input.isReminding) {
86    parts.push(`the model is reminded: the window is past ${percentText(input.settings.compactAt)}`);
87  }
88
89  if (input.lastCompact === undefined) {
90    parts.push('none at the model\'s request yet');
91  } else {
92    const when = localTime(input.lastCompact.at, input.now);
93    parts.push(input.lastCompact.skip === undefined ?
94      `last at the model's request at ${when}` :
95      `last asked at ${when}, skipped: ${input.lastCompact.skip}`);
96  }
97
98  if (input.compactPending) {
99    parts.push('refused during a turn, retried after it');
100  }
101
102  if (input.lastEngineCompact !== undefined) {
103    parts.push(`last by the engine (${input.lastEngineCompact.trigger}) at ${
104      localTime(input.lastEngineCompact.at, input.now)}`);
105  }
106
107  return parts.join('; ');
108}
109
110export function statusText(input: StatusInput): string {
111  const {settings} = input;
112  const windows = input.windows.length === 0 ?
113    'no reading yet (none off a subscription, or before the first response)' :
114    input.windows.map(window => windowText(window, input.now)).join(' · ');
115  return [
116    `windows: ${windows}`,
117    `context: ${contextText(input.context)}`,
118    `thresholds: compact at ${thresholdText(settings.compactAt)}, soft ${thresholdText(settings.limitSoft)}, hard ${
119      thresholdText(settings.limitHard)}, at hard: ${commandText(settings.atHard)}, at reset: ${
120      commandText(settings.atReset)}`,
121    `in force: ${inForceText(input)}`,
122    `compaction: ${compactionText(input)}`
123  ].join('\n');
124}
125

1// The subscription windows as the engine reports them, and everything the
2// plugin says about them: which are still open, which stands highest, what
3// the status line reads, and the texts of the warning and the refusal.
4
5import type {Settings} from './options.ts';
6
7import {localTime, parseIso, waitText} from './time.ts';
8
9export type Window = {
10  kind: string;
11  percentUsed: number;
12  resetsAt?: string;
13};
14
15const LABELS: Record<string, string> = {
16  five_hour: '5h',
17  seven_day: '7d',
18  spend_limit: 'spend'
19};
20
21const NAMES: Record<string, string> = {
22  five_hour: 'the 5-hour window',
23  seven_day: 'the 7-day window',
24  spend_limit: 'the spend limit'
25};
26
27export function windowLabel(kind: string): string {
28  return LABELS[kind] ?? kind;
29}
30
31export function windowName(kind: string): string {
32  return NAMES[kind] ?? `the ${kind} window`;
33}
34
35export function percentText(value: number): string {
36  return `${Number.isSafeInteger(value) ? value : value.toFixed(1)}%`;
37}
38
39// The windows whose reset is still ahead. A reading the engine keeps from
40// the last response outlives the window it describes: once the reset has
41// passed, the window is over and says nothing about the current one.
42export function liveWindows(windows: readonly Window[], now: number): Window[] {
43  return windows.filter(window => {
44    const resetsAt = parseIso(window.resetsAt);
45    return resetsAt === undefined || resetsAt > now;
46  });
47}
48
49// The window with the largest share; the first of equals.
50export function peakWindow(windows: readonly Window[]): undefined | Window {
51  return windows.reduce<undefined | Window>(
52    (peak, window) => (peak === undefined || window.percentUsed > peak.percentUsed ? window : peak),
53    undefined
54  );
55}
56
57export function windowsAbove(windows: readonly Window[], threshold: number): Window[] {
58  return threshold > 0 ? windows.filter(window => window.percentUsed >= threshold) : [];
59}
60
61// One crossing is one window of one kind: the same kind after a reset is a
62// new window, and its crossing is announced again.
63export function crossingKey(window: Window): string {
64  return `${window.kind}@${window.resetsAt ?? ''}`;
65}
66
67export type Crossings = {
68  hard: string[];
69  soft: string[];
70};
71
72export function crossingsOf(windows: readonly Window[], settings: Settings): Crossings {
73  return {
74    hard: windowsAbove(windows, settings.limitHard).map(crossingKey),
75    soft: windowsAbove(windows, settings.limitSoft).map(crossingKey)
76  };
77}
78
79// The keys present now and absent before.
80export function entered(previous: readonly string[], current: readonly string[]): string[] {
81  return current.filter(key => !previous.includes(key));
82}
83
84export function windowByKey(windows: readonly Window[], key: string): undefined | Window {
85  return windows.find(window => crossingKey(window) === key);
86}
87
88// The earliest reset ahead of now, in milliseconds since the epoch.
89export function nextResetAt(windows: readonly Window[], now: number): number | undefined {
90  const ahead = windows
91    .map(window => parseIso(window.resetsAt))
92    .filter((resetsAt): resetsAt is number => resetsAt !== undefined && resetsAt > now);
93  return ahead.length === 0 ? undefined : Math.min(...ahead);
94}
95
96// `5h 63% · 7d 41% · reset 18:40`; nothing without a reading.
97export function statusLine(windows: readonly Window[], now: number): string | undefined {
98  if (windows.length === 0) {
99    return undefined;
100  }
101
102  const parts = windows.map(window => `${windowLabel(window.kind)} ${percentText(window.percentUsed)}`);
103  const reset = nextResetAt(windows, now);
104  if (reset !== undefined) {
105    parts.push(`reset ${localTime(reset, now)}`);
106  }
107
108  return parts.join(' · ');
109}
110
111function resetText(window: Window, now: number): string {
112  const resetsAt = parseIso(window.resetsAt);
113  return resetsAt === undefined ?
114    'no reset time is known' :
115    `it resets at ${localTime(resetsAt, now)} (${waitText(resetsAt, now)})`;
116}
117
118// The toast's text, short: the engine draws it under the plugin's name in a
119// box a few lines high.
120export function softText(window: Window, threshold: number, now: number): string {
121  const resetsAt = parseIso(window.resetsAt);
122  const reset = resetsAt === undefined ? '' : `, resets ${localTime(resetsAt, now)} (${waitText(resetsAt, now)})`;
123  return `${windowName(window.kind)} is at ${percentText(window.percentUsed)}, past the soft limit of ${
124    percentText(threshold)}${reset}. Start nothing new.`;
125}
126
127// The line when the hard limit clears: which windows left it, and how (a
128// reset, or a share below the limit).
129export function clearedText(previousHard: readonly string[], live: readonly Window[]): string {
130  const how = previousHard.map(key => {
131    const kind = key.split('@', 1)[0] ?? key;
132    const stillLive = windowByKey(live, key);
133    return `${windowName(kind)} ${stillLive === undefined ? 'reset' : 'is below the limit'}`;
134  });
135  return `the hard limit is clear: ${how.join(', ')}; Bash, Write, Edit, NotebookEdit and new agents pass again`;
136}
137
138// Without the plugin's name: the guards add it for the model, and the
139// transcript line is printed under the name by the engine.
140export function denyText(window: Window, threshold: number, now: number): string {
141  return `${windowName(window.kind)} is at ${percentText(window.percentUsed)}, past the hard limit of ${
142    percentText(threshold)}; ${resetText(window, now)}. Bash, Write, Edit, NotebookEdit and new agents are refused ` +
143    'until then. Stop now: do not present unfinished work as finished; report what is done, what is half-done ' +
144    'and what remains.';
145}
146

1// The context window: the plugin never compacts on its own. Past the
2// threshold it reminds the model, on every tool result, to ask for a
3// compaction at a point of its own choosing; the model asks through the
4// plugin's tool, the conversation is compacted when that turn ends, and a
5// prompt wakes the model to go on. The reminders stop after a compaction
6// until a reading below the threshold: a summary may itself fill more than
7// the threshold, and asking again at once would loop.
8
9import {percentText} from './windows.ts';
10
11export const COMPACT_TOOL = 'mcp__smart-limits__compact';
12export const COMPACT_TOOL_NAME = 'compact';
13
14export const COMPACT_TOOL_DESCRIPTION = 'Compacts this conversation at the end of the current turn, at a point you ' +
15  'choose: call it when nothing is half-done, then end the turn with a short note of where you are. Pass ' +
16  'instructions: what the summary must keep (the task, its state, the next step). Once the conversation is ' +
17  'compacted, a prompt wakes you to continue. Main conversation only.';
18
19export const COMPACT_TOOL_SCHEMA = {
20  properties: {
21    instructions: {
22      description: 'What the summary must keep: the task, its state, the next step.',
23      type: 'string'
24    }
25  },
26  type: 'object'
27};
28
29export const WAKE_TEXT = 'The conversation was compacted at your request. Continue the work from the summary.';
30
31export const SUBAGENT_REFUSAL = 'smart-limits: the compact tool is for the main conversation; a subagent\'s ' +
32  'transcript is not compacted by the plugin. Go on with your task.';
33
34export enum CompactAction {
35  None = 'none',
36  Rearm = 'rearm',
37  Remind = 'remind'
38}
39
40// Armed while the fill was last seen below the threshold: at or above it the
41// model is reminded; after a compaction the plugin arms again only at a
42// reading below.
43export function compactAction(percent: number | undefined, compactAt: number, isArmed: boolean): CompactAction {
44  if (percent === undefined || compactAt <= 0) {
45    return CompactAction.None;
46  }
47
48  if (percent >= compactAt) {
49    return isArmed ? CompactAction.Remind : CompactAction.None;
50  }
51
52  return isArmed ? CompactAction.None : CompactAction.Rearm;
53}
54
55// What the model reads after a tool's result while a compaction is due.
56export function reminderText(percent: number, compactAt: number): string {
57  return `smart-limits: the context window is ${percentText(percent)} full, past the ${percentText(compactAt)} at ` +
58    'which this conversation should be compacted. Finish the current step at a point where nothing is half-done, ' +
59    'then call the smart-limits compact tool with what the summary must keep and end the turn; a prompt wakes you ' +
60    'after the compaction. Until then the engine may compact on its own in the middle of a step.';
61}
62
63// The compact tool's answer.
64export function requestAnswer(percent: number | undefined): string {
65  const at = percent === undefined ? '' : ` at ${percentText(percent)}`;
66  return `smart-limits: noted${at}: the conversation is compacted as soon as this turn ends, with your instructions. ` +
67    'End the turn now with a short note of where you are; a prompt wakes you afterwards.';
68}
69
70// The model's note first, the settings' standing instructions after it.
71export function joinInstructions(note: string, standing: string | undefined): string | undefined {
72  const parts = [note.trim(), standing?.trim() ?? ''].filter(part => part !== '');
73  return parts.length === 0 ? undefined : parts.join('\n\n');
74}
75

1// The plugin's settings as the manifest's userConfig fields arrive in
2// `register(on, options)`: three thresholds in percent, the compaction
3// instructions, and the commands run at the hard limit and after it clears.
4// A threshold of 0 turns its mechanism off, and so does a value that is not
5// a number.
6
7import type {PluginOptions} from 'claude-code';
8
9export type Command = {
10  args: string;
11  command: string;
12};
13
14export type Settings = {
15  atHard: Command | undefined;
16  atReset: Command | undefined;
17  compactAt: number;
18  compactInstructions: string | undefined;
19  limitHard: number;
20  limitSoft: number;
21  // What was set aside and why, for the person: one line each.
22  notes: string[];
23};
24
25export const DEFAULT_SETTINGS: Settings = {
26  atHard: undefined,
27  atReset: undefined,
28  compactAt: 70,
29  compactInstructions: undefined,
30  limitHard: 90,
31  limitSoft: 80,
32  notes: []
33};
34
35// A percentage from 0 to 100. Anything that is not a positive number is 0,
36// which switches the mechanism off; more than 100 is held to 100.
37export function parsePercent(value: unknown): number {
38  const number = typeof value === 'string' ? Number(value) : value;
39  return typeof number !== 'number' || !Number.isFinite(number) || number <= 0 ? 0 : Math.min(100, number);
40}
41
42// `name args` without the slash, as the person would type it after the
43// slash; a leading slash is forgiven. Empty means no command.
44export function parseCommand(value: unknown): Command | undefined {
45  if (typeof value !== 'string') {
46    return undefined;
47  }
48
49  const text = value.trim().replace(/^\//u, '');
50  if (text === '') {
51    return undefined;
52  }
53
54  const space = text.search(/\s/u);
55  return space === -1 ?
56    {
57      args: '',
58      command: text
59    } :
60    {
61      args: text.slice(space).trim(),
62      command: text.slice(0, space)
63    };
64}
65
66function parseText(value: unknown): string | undefined {
67  const text = typeof value === 'string' ? value.trim() : '';
68  return text === '' ? undefined : text;
69}
70
71type ParsedCommand = {
72  command: Command | undefined;
73  note: string | undefined;
74};
75
76// `ownPrefix` is the plugin's own command namespace (`smart-limits:`): the
77// engine does not route a plugin's command run back to the plugin's own
78// hooks, so such a command runs its markdown body instead, which tells the
79// model the module is not loaded. It is set aside with a note.
80function parseOwnOrOther(value: unknown, field: string, when: string, ownPrefix: string): ParsedCommand {
81  const command = parseCommand(value);
82  if (command === undefined || !command.command.startsWith(ownPrefix)) {
83    return {
84      command,
85      note: undefined
86    };
87  }
88
89  return {
90    command: undefined,
91    note: `the command ${when} (${field}), /${command.command}, is the plugin's own: the engine does not route it ` +
92      `back to the plugin, so nothing runs ${when}; name another command or leave the field empty`
93  };
94}
95
96export function parseSettings(options: PluginOptions, ownPrefix: string): Settings {
97  const atHard = parseOwnOrOther(options.atHard, 'atHard', 'at the hard limit', ownPrefix);
98  const atReset = parseOwnOrOther(options.atReset, 'atReset', 'after the hard limit clears', ownPrefix);
99  return {
100    atHard: atHard.command,
101    atReset: atReset.command,
102    compactAt: parsePercent(options.compactAt ?? DEFAULT_SETTINGS.compactAt),
103    compactInstructions: parseText(options.compactInstructions),
104    limitHard: parsePercent(options.limitHard ?? DEFAULT_SETTINGS.limitHard),
105    limitSoft: parsePercent(options.limitSoft ?? DEFAULT_SETTINGS.limitSoft),
106    notes: [atHard.note, atReset.note].filter((note): note is string => note !== undefined)
107  };
108}
109