fast-jev-compaction

1import type {
2  On,
3  PluginOptions,
4  Register,
5  SessionMessage,
6  ToolResultSummary,
7  ToolUseSummary,
8  TurnCompleteInput,
9} from 'claude-code';
10
11import { compact, reductionRatio, resolveOptions } from '../src/compact.js';
12import { buildJevRequest, DEFAULT_MODEL, parseJevResponse } from '../src/request.js';
13import type {
14  CompactOptions,
15  CompactResult,
16  JevAsker,
17  Message,
18  ToolResult,
19  ToolUse,
20} from '../src/types.js';
21
22const HOOK_DEFAULTS = {
23  compactAtPercent: 60,
24  minReductionRatio: 0.25,
25  model: DEFAULT_MODEL,
26};
27
28export type HookFetchInit = {
29  method?: string;
30  headers?: Record<string, string>;
31  body?: string;
32};
33
34export type HookFetchResponse = {
35  status: number;
36  ok: boolean;
37  text: string;
38};
39
40/** The shape of `$.http.fetch`, so the hook can be driven without an engine. */
41export type HookFetch = (url: string, init?: HookFetchInit) => Promise<HookFetchResponse>;
42
43export type HookConfig = CompactOptions & {
44  apiKey?: string;
45  compactAtPercent: number;
46  minReductionRatio: number;
47  model: string;
48};
49
50function optionNumber(options: PluginOptions, key: string, fallback: number): number {
51  const value = options[key];
52  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
53}
54
55function optionString(options: PluginOptions, key: string): string | undefined {
56  const value = options[key];
57  return typeof value === 'string' && value.length > 0 ? value : undefined;
58}
59
60/** Reads the plugin's `userConfig` values; anything missing takes the defaults. */
61export function resolveHookConfig(options: PluginOptions): HookConfig {
62  const numbers: Partial<Omit<CompactOptions, 'goal'>> = {};
63  for (const key of [
64    'keepThreshold',
65    'preserveRecentMessages',
66    'maxStateTokens',
67    'maxRequestTokens',
68    'truncateHeadChars',
69  ] as const) {
70    const value = options[key];
71    if (typeof value === 'number' && Number.isFinite(value)) numbers[key] = value;
72  }
73  const config: HookConfig = {
74    ...numbers,
75    compactAtPercent: optionNumber(options, 'compactAtPercent', HOOK_DEFAULTS.compactAtPercent),
76    minReductionRatio: optionNumber(
77      options,
78      'minReductionRatio',
79      HOOK_DEFAULTS.minReductionRatio,
80    ),
81    model: optionString(options, 'model') ?? HOOK_DEFAULTS.model,
82  };
83  const apiKey = optionString(options, 'apiKey');
84  if (apiKey) config.apiKey = apiKey;
85  const goal = optionString(options, 'goal');
86  if (goal) config.goal = goal;
87  return config;
88}
89
90/** A `JevAsker` over the engine's `$.http.fetch`. */
91export function jevAsker(fetchFn: HookFetch, apiKey: string, model: string): JevAsker {
92  return {
93    async ask(state, questions) {
94      const request = buildJevRequest({ apiKey, model }, state, questions);
95      const response = await fetchFn(request.url, {
96        method: request.method,
97        headers: request.headers,
98        body: request.body,
99      });
100      return parseJevResponse(response.status, response.ok, response.text);
101    },
102  };
103}
104
105function toolUseSummary(tool: ToolUse): ToolUseSummary {
106  const summary: ToolUseSummary = {
107    tool_use_id: tool.tool_use_id,
108    tool: tool.tool,
109    input: tool.input,
110  };
111  if (tool.text !== undefined) summary.text = tool.text;
112  if (tool.isError) summary.isError = true;
113  return summary;
114}
115
116function toolResultSummary(result: ToolResult): ToolResultSummary {
117  return {
118    tool_use_id: result.tool_use_id,
119    text: result.text,
120    isError: result.isError ?? false,
121  };
122}
123
124/**
125 * Maps the library's output back onto session messages. Whatever came back
126 * unchanged (a message, a tool use, a tool result) is the engine's own object,
127 * handle included; anything rebuilt is a fresh message without a handle, so the
128 * engine takes the edited content instead of its original.
129 */
130export function toSessionMessages(
131  input: readonly SessionMessage[],
132  output: readonly Message[],
133): SessionMessage[] {
134  const messages = new Map<Message, SessionMessage>();
135  const uses = new Map<ToolUse, ToolUseSummary>();
136  const results = new Map<ToolResult, ToolResultSummary>();
137  for (const message of input) {
138    messages.set(message, message);
139    for (const tool of message.toolUses) uses.set(tool, tool);
140    for (const result of message.toolResults ?? []) results.set(result, result);
141  }
142  return output.map((message) => {
143    const own = messages.get(message);
144    if (own) return own;
145    const rebuilt: SessionMessage = {
146      role: message.role,
147      text: message.text,
148      toolUses: message.toolUses.map((tool) => uses.get(tool) ?? toolUseSummary(tool)),
149    };
150    if (message.toolResults && message.toolResults.length > 0) {
151      rebuilt.toolResults = message.toolResults.map(
152        (result) => results.get(result) ?? toolResultSummary(result),
153      );
154    }
155    return rebuilt;
156  });
157}
158
159export type SessionCompaction = {
160  result: CompactResult;
161  messages: SessionMessage[];
162};
163
164/** Runs the library over a session transcript; throws when the key is missing or Jev fails. */
165export async function compactSession(
166  messages: readonly SessionMessage[],
167  config: HookConfig,
168  fetchFn: HookFetch,
169): Promise<SessionCompaction> {
170  if (!config.apiKey) throw new Error('TYPESAFE_API_KEY is not configured');
171  const result = await compact(messages, jevAsker(fetchFn, config.apiKey, config.model), config);
172  return { result, messages: toSessionMessages(messages, result.messages) };
173}
174
175function percent(ratio: number): string {
176  return `${Math.round(ratio * 100)}%`;
177}
178
179export function summarize(result: CompactResult): string {
180  const { stats } = result;
181  const parts = [
182    stats.kept > 0 ? `${stats.kept} kept` : '',
183    stats.resultsDropped > 0 ? `${stats.resultsDropped} results truncated` : '',
184    stats.callsDropped > 0 ? `${stats.callsDropped} call_dropped` : '',
185    stats.pinned > 0 ? `${stats.pinned} pinned` : '',
186  ].filter(Boolean);
187  return `${percent(reductionRatio(result))} reduction; ${
188    parts.join(', ') || 'no tool calls'
189  }; state ~${stats.stateTokens} tokens (${stats.stateStage}) in ${stats.requests} request(s)`;
190}
191
192const UI_LOG_MAX_CHARS = 4096;
193
194export function decisionLog(result: CompactResult): string {
195  return result.decisions
196    .filter((d) => d.reason !== 'pinned')
197    .map(
198      (d) =>
199        `${d.id}:${d.tool}:${d.action}/call=${d.keepCall.toFixed(2)}/result=${d.keepResult.toFixed(2)}`,
200    )
201    .join(' ');
202}
203
204export function decisionLogLines(
205  result: CompactResult,
206  maxChars: number = UI_LOG_MAX_CHARS,
207): string[] {
208  const entries = decisionLog(result).split(' ').filter(Boolean);
209  if (entries.length === 0) return ['decisions: (none)'];
210  const chunks: string[] = [];
211  let current = '';
212  for (const entry of entries) {
213    const next = current ? `${current} ${entry}` : entry;
214    if (current && next.length > maxChars - 24) {
215      chunks.push(current);
216      current = entry;
217    } else current = next;
218  }
219  chunks.push(current);
220  return chunks.map((chunk, index) =>
221    chunks.length === 1
222      ? `decisions: ${chunk}`
223      : `decisions (${index + 1}/${chunks.length}): ${chunk}`,
224  );
225}
226
227async function getApiKey(
228  $: {
229    env: { get: (name: string) => Promise<string | undefined> };
230    settings: { read: () => Promise<Readonly<Record<string, unknown>>> };
231  },
232  config: HookConfig,
233): Promise<string | undefined> {
234  if (config.apiKey) return config.apiKey;
235  const fromEnv = await $.env.get('TYPESAFE_API_KEY');
236  if (fromEnv) return fromEnv;
237  const settings = await $.settings.read();
238  const env = settings['env'];
239  if (env && typeof env === 'object') {
240    const value = (env as Record<string, unknown>)['TYPESAFE_API_KEY'];
241    if (typeof value === 'string' && value) return value;
242  }
243  return undefined;
244}
245
246function notify(
247  $: {
248    ui: {
249      log: (text: string) => void;
250      toast: (text: string, options?: { timeoutMs?: number }) => void;
251    };
252  },
253  text: string,
254): void {
255  $.ui.log(text);
256  $.ui.toast(text, { timeoutMs: 15_000 });
257}
258
259export const register: Register = (on: On, options: PluginOptions) => {
260  const configured = resolveHookConfig(options);
261  let compacting = false;
262
263  on('session.compact', async ($, event, next) => {
264    try {
265      const config = { ...configured, apiKey: await getApiKey($, configured) };
266      const { result, messages } = await compactSession(event.messages, config, async (url, init) => {
267        const response = await $.http.fetch(url, init);
268        return { status: response.status, ok: response.ok, text: response.text };
269      });
270      for (const line of decisionLogLines(result)) $.ui.log(line);
271      if (reductionRatio(result) < config.minReductionRatio) {
272        notify(
273          $,
274          `fallback to built-in summary (below ${percent(config.minReductionRatio)} minimum: ${summarize(result)})`,
275        );
276        return next(event);
277      }
278      notify(
279        $,
280        `kept ${messages.length}/${event.messages.length} messages, no summary (${summarize(result)})`,
281      );
282      return { messages };
283    } catch (error) {
284      notify(
285        $,
286        `fallback to built-in summary (${error instanceof Error ? error.message : String(error)})`,
287      );
288      return next(event);
289    }
290  });
291
292  on('turn.complete', async ($, event: TurnCompleteInput, next) => {
293    if (compacting) return next(event);
294    try {
295      const { context } = await $.session.usage();
296      if ((context.percent ?? 0) < configured.compactAtPercent) return next(event);
297      compacting = true;
298      await $.session.compact();
299    } catch (error) {
300      $.ui.log(
301        `auto-compact skipped (${error instanceof Error ? error.message : String(error)})`,
302      );
303    } finally {
304      compacting = false;
305    }
306    return next(event);
307  });
308};
309
310export { resolveOptions };
311

1import { noulAnswer } from './request.js';
2import { collectToolCalls, estimateTokens, fitState } from './state.js';
3import type {
4  CallAnswer,
5  CallDecision,
6  CompactOptions,
7  CompactResult,
8  CompactionState,
9  JevAsker,
10  JevQuestions,
11  Message,
12  ResolvedCompactOptions,
13  ToolCall,
14  ToolUse,
15} from './types.js';
16
17export const DEFAULT_OPTIONS: ResolvedCompactOptions = {
18  goal: '',
19  keepThreshold: 0.5,
20  preserveRecentMessages: 6,
21  maxStateTokens: 25_000,
22  maxRequestTokens: 30_000,
23  truncateHeadChars: 300,
24};
25
26/** Tokens the request envelope (`model`, key names) adds around state and questions. */
27const REQUEST_OVERHEAD_TOKENS = 20;
28
29function finite(value: number | undefined, fallback: number): number {
30  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
31}
32
33export function resolveOptions(options: CompactOptions = {}): ResolvedCompactOptions {
34  return {
35    goal: options.goal ?? DEFAULT_OPTIONS.goal,
36    keepThreshold: finite(options.keepThreshold, DEFAULT_OPTIONS.keepThreshold),
37    preserveRecentMessages: Math.max(
38      0,
39      Math.floor(
40        finite(options.preserveRecentMessages, DEFAULT_OPTIONS.preserveRecentMessages),
41      ),
42    ),
43    maxStateTokens: Math.max(1, finite(options.maxStateTokens, DEFAULT_OPTIONS.maxStateTokens)),
44    maxRequestTokens: Math.max(
45      1,
46      finite(options.maxRequestTokens, DEFAULT_OPTIONS.maxRequestTokens),
47    ),
48    truncateHeadChars: Math.max(
49      0,
50      Math.floor(finite(options.truncateHeadChars, DEFAULT_OPTIONS.truncateHeadChars)),
51    ),
52  };
53}
54
55/** The two `noul` questions asked about one call: keep the call, keep its result. */
56export function questionsFor(call: ToolCall): JevQuestions {
57  return {
58    [`call_${call.id}`]: {
59      type: 'noul',
60      instructions: `Tool call ${call.id} (${call.tool}) should stay in the history: knowing this call was made, with its input, still matters for what the assistant does next`,
61    },
62    [`result_${call.id}`]: {
63      type: 'noul',
64      instructions: `The full output of tool call ${call.id} (${call.tool}, ${call.resultChars} chars) should stay in the history verbatim: the assistant still needs its contents and re-running the tool would not do`,
65    },
66  };
67}
68
69/**
70 * Splits the candidate calls into batches whose questions, together with the
71 * (always complete) state, fit one request.
72 */
73export function batchCalls(
74  calls: readonly ToolCall[],
75  stateTokens: number,
76  options: Pick<ResolvedCompactOptions, 'maxRequestTokens'>,
77): ToolCall[][] {
78  const budget = options.maxRequestTokens - stateTokens - REQUEST_OVERHEAD_TOKENS;
79  const batches: ToolCall[][] = [];
80  let current: ToolCall[] = [];
81  let currentTokens = 0;
82  for (const call of calls) {
83    const tokens = estimateTokens(JSON.stringify(questionsFor(call)));
84    if (current.length > 0 && currentTokens + tokens > budget) {
85      batches.push(current);
86      current = [];
87      currentTokens = 0;
88    }
89    if (current.length === 0 && tokens > budget) {
90      throw new Error(
91        `state leaves no room for questions (~${stateTokens} of ${options.maxRequestTokens} tokens)`,
92      );
93    }
94    current.push(call);
95    currentTokens += tokens;
96  }
97  if (current.length > 0) batches.push(current);
98  return batches;
99}
100
101export function decideCall(
102  call: Pick<ToolCall, 'id' | 'tool' | 'pinned'>,
103  answer: CallAnswer,
104  options: Pick<ResolvedCompactOptions, 'keepThreshold'>,
105): CallDecision {
106  const base = { id: call.id, tool: call.tool, ...answer };
107  if (call.pinned) return { ...base, action: 'keep', reason: 'pinned' };
108  if (answer.keepResult >= options.keepThreshold) {
109    return { ...base, action: 'keep', reason: 'kept' };
110  }
111  if (answer.keepCall >= options.keepThreshold) {
112    return { ...base, action: 'drop_result', reason: 'result_dropped' };
113  }
114  return { ...base, action: 'drop_call', reason: 'call_dropped' };
115}
116
117async function askBatch(
118  asker: JevAsker,
119  state: CompactionState,
120  batch: readonly ToolCall[],
121): Promise<Map<string, CallAnswer>> {
122  const questions: JevQuestions = Object.assign({}, ...batch.map(questionsFor));
123  const { answers } = await asker.ask(state, questions);
124  return new Map(
125    batch.map((call) => [
126      call.id,
127      {
128        keepCall: noulAnswer(answers, `call_${call.id}`),
129        keepResult: noulAnswer(answers, `result_${call.id}`),
130      },
131    ]),
132  );
133}
134
135function truncatedResultText(text: string, isError: boolean, headChars: number): string {
136  if (text.length <= headChars + 120) return text;
137  const head = headChars > 0 ? `${text.slice(0, headChars)}\n` : '';
138  return `${head}[fast-jev-compaction truncated ${text.length - headChars} chars of this tool result${
139    isError ? ' (error)' : ''
140  }; re-run the tool if needed]`;
141}
142
143/**
144 * Rebuilds the conversation from the decisions. A dropped call disappears
145 * together with its result; a dropped result keeps a bounded head and note.
146 * Messages that lose all their content are removed; untouched messages are
147 * returned as the same objects they came in as.
148 */
149export function applyDecisions(
150  messages: readonly Message[],
151  decisions: readonly CallDecision[],
152  calls: readonly ToolCall[],
153  headChars: number,
154): Message[] {
155  const byId = new Map(calls.map((call) => [call.id, call]));
156  const actions = new Map<string, CallDecision['action']>();
157  for (const decision of decisions) {
158    const call = byId.get(decision.id);
159    if (call && decision.action !== 'keep') actions.set(call.tool_use_id, decision.action);
160  }
161  const kept: Message[] = [];
162  for (const message of messages) {
163    const touched =
164      message.toolUses.some((tool) => actions.has(tool.tool_use_id)) ||
165      (message.toolResults ?? []).some((result) => actions.has(result.tool_use_id));
166    if (!touched) {
167      kept.push(message);
168      continue;
169    }
170    const toolUses = message.toolUses
171      .filter((tool) => actions.get(tool.tool_use_id) !== 'drop_call')
172      .map((tool) => {
173        if (actions.get(tool.tool_use_id) !== 'drop_result') return tool;
174        const text = truncatedResultText(
175          tool.text ?? '',
176          tool.isError ?? false,
177          headChars,
178        );
179        if ((tool.text ?? '') === text) return tool;
180        const copy: ToolUse = {
181          tool_use_id: tool.tool_use_id,
182          tool: tool.tool,
183          input: tool.input,
184          text,
185        };
186        if (tool.isError) copy.isError = true;
187        return copy;
188      });
189    const toolResults = (message.toolResults ?? [])
190      .filter((result) => actions.get(result.tool_use_id) !== 'drop_call')
191      .map((result) => {
192        if (actions.get(result.tool_use_id) !== 'drop_result') return result;
193        const text = truncatedResultText(result.text, result.isError ?? false, headChars);
194        return text === result.text
195          ? result
196          : {
197              tool_use_id: result.tool_use_id,
198              text,
199              isError: result.isError,
200            };
201      });
202    if (
203      !message.toolUses.some(
204        (tool) => actions.get(tool.tool_use_id) === 'drop_call',
205      ) &&
206      !(message.toolResults ?? []).some(
207        (result) => actions.get(result.tool_use_id) === 'drop_call',
208      ) &&
209      toolUses.every((tool, index) => tool === message.toolUses[index]) &&
210      toolResults.every(
211        (result, index) => result === message.toolResults?.[index],
212      )
213    ) {
214      kept.push(message);
215      continue;
216    }
217    if (message.text.trim().length === 0 && toolUses.length === 0 && toolResults.length === 0) {
218      continue;
219    }
220    const rebuilt: Message = { role: message.role, text: message.text, toolUses };
221    if (toolResults.length > 0) rebuilt.toolResults = toolResults;
222    kept.push(rebuilt);
223  }
224  return kept;
225}
226
227/** Characters of text, tool input and tool output a message holds. */
228export function messageChars(message: Message): number {
229  let total = message.text.length;
230  for (const tool of message.toolUses) {
231    try {
232      total += JSON.stringify(tool.input).length;
233    } catch {
234      total += 20;
235    }
236  }
237  for (const result of message.toolResults ?? []) total += result.text.length;
238  return total;
239}
240
241export function reductionRatio(result: Pick<CompactResult, 'stats'>): number {
242  const { charsBefore, charsAfter } = result.stats;
243  return charsBefore === 0 ? 0 : (charsBefore - charsAfter) / charsBefore;
244}
245
246function count(decisions: readonly CallDecision[], reason: CallDecision['reason']): number {
247  return decisions.filter((decision) => decision.reason === reason).length;
248}
249
250/**
251 * Compacts a transcript by asking Jev, for every tool call outside the pinned
252 * first and newest messages, whether the call and whether its result must
253 * stay. The whole history (results omitted, fitted into `maxStateTokens`) is
254 * sent as state with every batch of questions. Throws when Jev fails or the
255 * history cannot be fitted; the caller decides whether to fall back.
256 */
257export async function compact(
258  messages: readonly Message[],
259  asker: JevAsker,
260  options: CompactOptions = {},
261): Promise<CompactResult> {
262  const started = Date.now();
263  const resolved = resolveOptions(options);
264  const calls = collectToolCalls(messages, resolved.preserveRecentMessages);
265  const candidates = calls.filter((call) => !call.pinned);
266  const charsBefore = messages.reduce((sum, message) => sum + messageChars(message), 0);
267
268  let fitted: { tokens: number; stage: string } = { tokens: 0, stage: '' };
269  let batches: ToolCall[][] = [];
270  const answers = new Map<string, CallAnswer>();
271  if (candidates.length > 0) {
272    const state = fitState(messages, calls, resolved);
273    fitted = state;
274    batches = batchCalls(candidates, state.tokens, resolved);
275    const answered = await Promise.all(
276      batches.map((batch) => askBatch(asker, state.state, batch)),
277    );
278    for (const map of answered) for (const [id, answer] of map) answers.set(id, answer);
279  }
280
281  const decisions = calls.map((call) =>
282    decideCall(call, answers.get(call.id) ?? { keepCall: 1, keepResult: 1 }, resolved),
283  );
284  const kept = applyDecisions(
285    messages,
286    decisions,
287    calls,
288    resolved.truncateHeadChars,
289  );
290  return {
291    messages: kept,
292    decisions,
293    stats: {
294      messagesBefore: messages.length,
295      messagesAfter: kept.length,
296      charsBefore,
297      charsAfter: kept.reduce((sum, message) => sum + messageChars(message), 0),
298      calls: calls.length,
299      kept: count(decisions, 'kept'),
300      resultsDropped: count(decisions, 'result_dropped'),
301      callsDropped: count(decisions, 'call_dropped'),
302      pinned: count(decisions, 'pinned'),
303      stateTokens: fitted.tokens,
304      stateStage: fitted.stage,
305      requests: batches.length,
306      ms: Date.now() - started,
307    },
308  };
309}
310

1import type { JevAnswer, JevQuestions, JevResponse, JevState } from './types.js';
2
3export const SYSTEM_ONE_URL = 'https://api.typesafe.ai/v1/systemone';
4export const DEFAULT_MODEL = 'jev-latest';
5
6export interface JevRequest {
7  url: string;
8  method: 'POST';
9  headers: Record<string, string>;
10  body: string;
11}
12
13/** The HTTP request for one Jev call, for any fetch-like transport. */
14export function buildJevRequest(
15  params: {
16    apiKey: string;
17    model?: string;
18    baseUrl?: string;
19  },
20  state: JevState,
21  questions: JevQuestions,
22): JevRequest {
23  return {
24    url: params.baseUrl ?? SYSTEM_ONE_URL,
25    method: 'POST',
26    headers: {
27      authorization: `Bearer ${params.apiKey}`,
28      'content-type': 'application/json',
29    },
30    body: JSON.stringify({
31      model: params.model ?? DEFAULT_MODEL,
32      state,
33      questions,
34    }),
35  };
36}
37
38/** Validates a Jev response body; throws on anything but an `answers` object. */
39export function parseJevResponse(
40  status: number,
41  ok: boolean,
42  text: string,
43): JevResponse {
44  if (!ok) {
45    throw new Error(`Jev request failed (${status}): ${text.slice(0, 200)}`);
46  }
47  let parsed: unknown;
48  try {
49    parsed = JSON.parse(text);
50  } catch {
51    throw new Error('Jev returned malformed JSON');
52  }
53  if (
54    parsed === null ||
55    typeof parsed !== 'object' ||
56    !('answers' in parsed) ||
57    parsed.answers === null ||
58    typeof parsed.answers !== 'object'
59  ) {
60    throw new Error('Jev response is missing answers');
61  }
62  return parsed as JevResponse;
63}
64
65/** The `noul` probability of one answer; throws when it is not there. */
66export function noulAnswer(
67  answers: Record<string, JevAnswer>,
68  name: string,
69): number {
70  const answer = answers[name];
71  if (
72    !answer ||
73    !('noul' in answer) ||
74    typeof answer.noul !== 'number' ||
75    !Number.isFinite(answer.noul)
76  ) {
77    throw new Error(`Invalid Jev answer for ${name}`);
78  }
79  return answer.noul;
80}
81

1export type Role = 'user' | 'assistant';
2
3/**
4 * A tool_use block of an assistant message. `text` and `isError` mirror the
5 * outcome once the transcript holds it (Claude Code attaches them).
6 */
7export interface ToolUse {
8  tool_use_id: string;
9  tool: string;
10  input: Record<string, unknown>;
11  text?: string;
12  isError?: boolean;
13}
14
15/** A tool_result block of a user message. */
16export interface ToolResult {
17  tool_use_id: string;
18  text: string;
19  isError?: boolean;
20}
21
22/**
23 * One transcript message. The shape is a subset of Claude Code's
24 * `SessionMessage`, so a session transcript can be passed in as is.
25 */
26export interface Message {
27  role: Role;
28  text: string;
29  toolUses: ToolUse[];
30  toolResults?: ToolResult[];
31}
32
33/** A tool call paired with its result by `tool_use_id`. */
34export interface ToolCall {
35  /** Short id used in the Jev state and question names (`t1`, `t2`, ...). */
36  id: string;
37  tool_use_id: string;
38  tool: string;
39  input: Record<string, unknown>;
40  /** Index of the message holding the tool_use block. */
41  callIndex: number;
42  /** Index of the message holding the tool_result block. */
43  resultIndex: number;
44  resultChars: number;
45  isError: boolean;
46  /** In the first or the newest preserved messages; never a candidate. */
47  pinned: boolean;
48}
49
50export interface CallAnswer {
51  /** Jev's probability that the call itself still matters. */
52  keepCall: number;
53  /** Jev's probability that the full result still needs to stay verbatim. */
54  keepResult: number;
55}
56
57export type CallAction = 'keep' | 'drop_result' | 'drop_call';
58
59export interface CallDecision extends CallAnswer {
60  id: string;
61  tool: string;
62  action: CallAction;
63  reason: 'pinned' | 'kept' | 'result_dropped' | 'call_dropped';
64}
65
66export interface HistoryToolCall {
67  id: string;
68  tool: string;
69  input: string;
70  result: string;
71}
72
73export interface HistoryEntry {
74  i: number;
75  role: Role;
76  text: string;
77  /** Structured per call, or one compact line per call once the state has to shrink. */
78  tool_calls?: HistoryToolCall[] | string[];
79}
80
81/** The state sent with every Jev request: the whole history, results omitted. */
82export interface CompactionState {
83  context: string;
84  goal: string;
85  history: HistoryEntry[];
86}
87
88export interface FittedState {
89  state: CompactionState;
90  tokens: number;
91  /** Which fitting stage produced the state, for diagnostics. */
92  stage: string;
93}
94
95export interface CompactOptions {
96  /** Ongoing task description; defaults to the last few user prompts. */
97  goal?: string;
98  /** Minimum keep probability for a call or result to stay. Default 0.5. */
99  keepThreshold?: number;
100  /** Newest messages never touched (the first message is always kept). Default 6. */
101  preserveRecentMessages?: number;
102  /** Estimated token ceiling for the state. Default 25000. */
103  maxStateTokens?: number;
104  /** Estimated token ceiling for state plus one batch of questions. Default 30000. */
105  maxRequestTokens?: number;
106  /** Characters of a dropped tool result to retain. Default 300. */
107  truncateHeadChars?: number;
108}
109
110export interface ResolvedCompactOptions {
111  goal: string;
112  keepThreshold: number;
113  preserveRecentMessages: number;
114  maxStateTokens: number;
115  maxRequestTokens: number;
116  truncateHeadChars: number;
117}
118
119export interface CompactResult {
120  /** The compacted transcript; untouched messages are the input objects. */
121  messages: Message[];
122  decisions: CallDecision[];
123  stats: {
124    messagesBefore: number;
125    messagesAfter: number;
126    charsBefore: number;
127    charsAfter: number;
128    calls: number;
129    kept: number;
130    resultsDropped: number;
131    callsDropped: number;
132    pinned: number;
133    stateTokens: number;
134    /** Which fitting stage the state needed, '' when no request was made. */
135    stateStage: string;
136    requests: number;
137    ms: number;
138  };
139}
140
141/** The `state` of a Jev request: a string or any JSON-serialisable object. */
142export type JevState = string | object;
143
144export interface NoulQuestion {
145  type: 'noul';
146  instructions: string;
147  criteria?: {
148    true?: string;
149    false?: string;
150  };
151}
152
153export interface ChoiceQuestion {
154  type: 'choice';
155  instructions: string;
156  criteria: Record<string, string | null>;
157}
158
159export interface ScoreQuestion {
160  type: 'score';
161  instructions: string;
162  criteria: string[];
163}
164
165export type JevQuestion = NoulQuestion | ChoiceQuestion | ScoreQuestion;
166export type JevQuestions = Record<string, JevQuestion>;
167
168export interface NoulAnswer {
169  type?: 'noul';
170  noul: number;
171}
172
173export interface ChoiceAnswer {
174  type?: 'choice';
175  choice: string;
176  confidence: number;
177  probabilities: Record<string, number>;
178}
179
180export interface ScoreAnswer {
181  type?: 'score';
182  score: number;
183  confidence: number;
184  probabilities: Record<string, number>;
185}
186
187export type JevAnswer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
188
189export interface JevResponse {
190  model?: string;
191  answers: Record<string, JevAnswer>;
192  usage?: {
193    input_tokens?: number;
194    output_tokens?: number;
195  };
196  [key: string]: unknown;
197}
198
199/** Anything that can answer Jev questions: `JevClient`, or a host-provided adapter. */
200export interface JevAsker {
201  ask(state: JevState, questions: JevQuestions): Promise<JevResponse>;
202}
203

1import type {
2  CompactionState,
3  FittedState,
4  HistoryEntry,
5  Message,
6  ResolvedCompactOptions,
7  ToolCall,
8  ToolResult,
9} from './types.js';
10
11export const STATE_CONTEXT =
12  'A coding assistant conversation is being compacted to free context. `history` is the whole conversation so far, oldest first; tool outputs are replaced by a short `result` note and long texts may be abridged. Each question asks whether one tool call, or the full output of that call, still needs to stay in the history verbatim. Whatever is not kept is deleted permanently, but the assistant can always re-run a tool or re-read a file.';
13
14/** Successive caps on the serialised tool input included per call. */
15const INPUT_CHARS = [1000, 200, 60] as const;
16const TEXT_HEAD = 400;
17const TEXT_TAIL = 150;
18
19const TOKEN_PIECES = /[A-Za-z]+|\d+|[^\sA-Za-z\d]/g;
20
21/**
22 * Estimates tokens without a tokenizer: a word costs one token per six
23 * letters, a digit half a token, any other symbol nine tenths. Calibrated
24 * against the usage Jev reports for real transcripts, where it lands 2–18%
25 * above the true count; a plain characters-per-token ratio undercounts the
26 * JSON-heavy states by up to 40%.
27 */
28export function estimateTokens(text: string): number {
29  let tokens = 0;
30  for (const [piece] of text.matchAll(TOKEN_PIECES)) {
31    const first = piece.charCodeAt(0);
32    if (first >= 48 && first <= 57) tokens += piece.length / 2;
33    else if ((first >= 65 && first <= 90) || (first >= 97 && first <= 122)) {
34      tokens += 1 + Math.floor((piece.length - 1) / 6);
35    } else tokens += 0.9;
36  }
37  return Math.ceil(tokens);
38}
39
40export function truncate(text: string, limit: number): string {
41  return text.length <= limit ? text : `${text.slice(0, Math.max(0, limit - 1))}…`;
42}
43
44function abridge(text: string, head: number, tail: number): string {
45  if (text.length <= head + tail + 40) return text;
46  const omitted = text.length - head - tail;
47  return `${text.slice(0, head)}\n[… ${omitted} chars omitted …]\n${text.slice(-tail)}`;
48}
49
50export function isPinned(
51  index: number,
52  total: number,
53  preserveRecentMessages: number,
54): boolean {
55  return index === 0 || index >= total - preserveRecentMessages;
56}
57
58/**
59 * Pairs every tool_use with its tool_result by `tool_use_id`. Calls without a
60 * result are not candidates (there is nothing to drop yet).
61 */
62export function collectToolCalls(
63  messages: readonly Message[],
64  preserveRecentMessages: number,
65): ToolCall[] {
66  const results = new Map<string, { index: number; result: ToolResult }>();
67  messages.forEach((message, index) => {
68    for (const result of message.toolResults ?? []) {
69      results.set(result.tool_use_id, { index, result });
70    }
71  });
72  const calls: ToolCall[] = [];
73  messages.forEach((message, callIndex) => {
74    for (const tool of message.toolUses) {
75      const found = results.get(tool.tool_use_id);
76      if (!found) continue;
77      calls.push({
78        id: `t${calls.length + 1}`,
79        tool_use_id: tool.tool_use_id,
80        tool: tool.tool,
81        input: tool.input,
82        callIndex,
83        resultIndex: found.index,
84        resultChars: found.result.text.length,
85        isError: found.result.isError ?? false,
86        pinned:
87          isPinned(callIndex, messages.length, preserveRecentMessages) ||
88          isPinned(found.index, messages.length, preserveRecentMessages),
89      });
90    }
91  });
92  return calls;
93}
94
95function inputText(input: Record<string, unknown>, limit: number): string {
96  let json = '';
97  try {
98    json = JSON.stringify(input);
99  } catch {
100    json = '[unserializable input]';
101  }
102  return truncate(json, limit);
103}
104
105function resultNote(call: ToolCall): string {
106  return `${call.isError ? 'error' : 'ok'}, ${call.resultChars} chars (omitted)`;
107}
108
109/** One call as a single line, for when the structured form is too costly. */
110function compactCall(call: ToolCall): string {
111  const input = Object.entries(call.input)
112    .map(([key, value]) => {
113      const text = typeof value === 'string' ? value : inputText({ [key]: value }, 200);
114      return `${key}=${text.replace(/\s+/g, ' ')}`;
115    })
116    .join(' ');
117  return `${call.id} ${call.tool} ${truncate(input, INPUT_CHARS[2])} → ${
118    call.isError ? 'error' : 'ok'
119  } ${call.resultChars}ch`;
120}
121
122/**
123 * Folds runs of adjacent call-only entries into one entry each, so the
124 * per-entry envelope is paid once per run; the call lines keep their ids.
125 */
126function mergeCallRuns(history: readonly HistoryEntry[], pinned: (e: HistoryEntry) => boolean): HistoryEntry[] {
127  const merged: HistoryEntry[] = [];
128  for (const entry of history) {
129    const previous = merged[merged.length - 1];
130    const foldable = (e: HistoryEntry): boolean =>
131      !pinned(e) && e.text.length === 0 && typeof e.tool_calls?.[0] === 'string';
132    if (previous && foldable(previous) && foldable(entry) && previous.role === entry.role) {
133      previous.tool_calls = [...(previous.tool_calls as string[]), ...(entry.tool_calls as string[])];
134      continue;
135    }
136    merged.push({ ...entry });
137  }
138  return merged;
139}
140
141function callsByMessage(calls: readonly ToolCall[]): Map<number, ToolCall[]> {
142  const byMessage = new Map<number, ToolCall[]>();
143  for (const call of calls) {
144    const list = byMessage.get(call.callIndex) ?? [];
145    list.push(call);
146    byMessage.set(call.callIndex, list);
147  }
148  return byMessage;
149}
150
151function historyEntries(
152  messages: readonly Message[],
153  calls: readonly ToolCall[],
154  inputChars: number,
155): HistoryEntry[] {
156  const byMessage = callsByMessage(calls);
157  const entries: HistoryEntry[] = [];
158  messages.forEach((message, i) => {
159    const toolCalls = (byMessage.get(i) ?? []).map((call) => ({
160      id: call.id,
161      tool: call.tool,
162      input: inputText(call.input, inputChars),
163      result: resultNote(call),
164    }));
165    if (message.text.trim().length === 0 && toolCalls.length === 0) return;
166    const entry: HistoryEntry = { i, role: message.role, text: message.text };
167    if (toolCalls.length > 0) entry.tool_calls = toolCalls;
168    entries.push(entry);
169  });
170  return entries;
171}
172
173/** The last three user prompts, as the default `goal`. */
174export function goalFromMessages(messages: readonly Message[]): string {
175  return messages
176    .filter(
177      (message) =>
178        message.role === 'user' &&
179        message.text.trim().length > 0 &&
180        (message.toolResults ?? []).length === 0,
181    )
182    .slice(-3)
183    .map((message) => truncate(message.text, 500))
184    .join('\n');
185}
186
187/**
188 * Builds the Jev state from the whole conversation and shrinks it in stages
189 * until it fits `maxStateTokens`: tool inputs are truncated, then long texts
190 * are abridged oldest-first (pinned messages last), then old messages collapse
191 * to a one-line note, then old tool calls shrink to one line each, then old
192 * messages that carry no call are left out, then runs of old call-only
193 * messages are folded into one entry. Throws when even that is too big.
194 */
195export function fitState(
196  messages: readonly Message[],
197  calls: readonly ToolCall[],
198  options: Pick<ResolvedCompactOptions, 'maxStateTokens' | 'preserveRecentMessages' | 'goal'>,
199): FittedState {
200  const goal = options.goal || goalFromMessages(messages);
201  const stateOf = (history: HistoryEntry[]): CompactionState => ({
202    context: STATE_CONTEXT,
203    goal,
204    history,
205  });
206  const entryTokens = (entry: HistoryEntry): number => estimateTokens(JSON.stringify(entry)) + 1;
207  const baseTokens = estimateTokens(JSON.stringify(stateOf([])));
208  const fitted = (history: HistoryEntry[], tokens: number, stage: string): FittedState => ({
209    state: stateOf(history),
210    tokens,
211    stage,
212  });
213
214  let history: HistoryEntry[] = [];
215  let perEntry: number[] = [];
216  let tokens = 0;
217  const rebuild = (inputChars: number): void => {
218    history = historyEntries(messages, calls, inputChars);
219    perEntry = history.map(entryTokens);
220    tokens = baseTokens + perEntry.reduce((sum, n) => sum + n, 0);
221  };
222  const fits = (): boolean => tokens <= options.maxStateTokens;
223  const shrink = (index: number, change: (entry: HistoryEntry) => void): void => {
224    const entry = history[index];
225    if (!entry) return;
226    change(entry);
227    const now = entryTokens(entry);
228    tokens += now - (perEntry[index] ?? 0);
229    perEntry[index] = now;
230  };
231
232  rebuild(INPUT_CHARS[0]);
233  if (fits()) return fitted(history, tokens, 'full');
234
235  for (const limit of INPUT_CHARS.slice(1)) {
236    rebuild(limit);
237    if (fits()) return fitted(history, tokens, `inputs<=${limit}`);
238  }
239
240  const pinned = (entry: HistoryEntry): boolean =>
241    isPinned(entry.i, messages.length, options.preserveRecentMessages);
242  const indices = history.map((_, index) => index);
243  const order = [
244    ...indices.filter((index) => !pinned(history[index]!)),
245    ...indices.filter((index) => pinned(history[index]!)),
246  ];
247
248  for (const index of order) {
249    const entry = history[index]!;
250    if (entry.text.length <= TEXT_HEAD + TEXT_TAIL + 40) continue;
251    shrink(index, (e) => {
252      e.text = abridge(e.text, TEXT_HEAD, TEXT_TAIL);
253    });
254    if (fits()) return fitted(history, tokens, 'texts abridged');
255  }
256
257  for (const index of order) {
258    const entry = history[index]!;
259    if (pinned(entry) || entry.text.length === 0) continue;
260    const original = messages[entry.i]?.text.length ?? entry.text.length;
261    shrink(index, (e) => {
262      e.text = `[… ${original} chars omitted …]`;
263    });
264    if (fits()) return fitted(history, tokens, 'old messages collapsed');
265  }
266
267  const byMessage = callsByMessage(calls);
268  for (const index of order) {
269    const entry = history[index]!;
270    const own = byMessage.get(entry.i);
271    if (pinned(entry) || !own) continue;
272    shrink(index, (e) => {
273      e.tool_calls = own.map(compactCall);
274    });
275    if (fits()) return fitted(history, tokens, 'old calls compacted');
276  }
277
278  const left = new Set<number>();
279  for (const index of order) {
280    const entry = history[index]!;
281    if (pinned(entry) || entry.tool_calls) continue;
282    left.add(index);
283    tokens -= perEntry[index] ?? 0;
284    if (fits()) {
285      return fitted(
286        history.filter((_, i) => !left.has(i)),
287        tokens,
288        'old messages left out',
289      );
290    }
291  }
292
293  history = mergeCallRuns(
294    history.filter((_, i) => !left.has(i)),
295    pinned,
296  );
297  perEntry = history.map(entryTokens);
298  tokens = baseTokens + perEntry.reduce((sum, n) => sum + n, 0);
299  if (fits()) return fitted(history, tokens, 'old calls merged');
300
301  throw new Error(
302    `history too large for Jev (~${tokens} tokens after truncation, limit ${options.maxStateTokens})`,
303  );
304}
305