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

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