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  /** JFC fork: endpoint override (Vercel AI Gateway's TypeSafe-compatible API). */
46  baseUrl?: string;
47  compactAtPercent: number;
48  minReductionRatio: number;
49  model: string;
50};
51
52function optionNumber(options: PluginOptions, key: string, fallback: number): number {
53  const value = options[key];
54  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
55}
56
57function optionString(options: PluginOptions, key: string): string | undefined {
58  const value = options[key];
59  return typeof value === 'string' && value.length > 0 ? value : undefined;
60}
61
62/** Reads the plugin's `userConfig` values; anything missing takes the defaults. */
63export function resolveHookConfig(options: PluginOptions): HookConfig {
64  const numbers: Partial<Omit<CompactOptions, 'goal'>> = {};
65  for (const key of [
66    'keepThreshold',
67    'preserveRecentMessages',
68    'maxStateTokens',
69    'maxRequestTokens',
70    'truncateHeadChars',
71  ] as const) {
72    const value = options[key];
73    if (typeof value === 'number' && Number.isFinite(value)) numbers[key] = value;
74  }
75  const config: HookConfig = {
76    ...numbers,
77    compactAtPercent: optionNumber(options, 'compactAtPercent', HOOK_DEFAULTS.compactAtPercent),
78    minReductionRatio: optionNumber(
79      options,
80      'minReductionRatio',
81      HOOK_DEFAULTS.minReductionRatio,
82    ),
83    model: optionString(options, 'model') ?? HOOK_DEFAULTS.model,
84  };
85  const apiKey = optionString(options, 'apiKey');
86  if (apiKey) config.apiKey = apiKey;
87  const goal = optionString(options, 'goal');
88  if (goal) config.goal = goal;
89  return config;
90}
91
92/** A `JevAsker` over the engine's `$.http.fetch`. */
93/* ---------------------------------------------------------------------------
94   JFC fork (2026-09-24): redact before sending. The upstream plugin sends the
95   conversation (user/assistant text + tool inputs, results abridged) to Jev.
96   JFC's sessions can show app licenses, PINs and keys; those never leave the
97   machine. Patterns are a backstop, not a promise: never paste customer data.
98   --------------------------------------------------------------------------- */
99const REDACTIONS: Array<[RegExp, string]> = [
100  [/\b(?:F123|AMG|C123)-[A-Z0-9][A-Z0-9-]{3,}\b/gi, '[license]'],
101  [/\b(?:vck|sk|pk|rk)[-_][A-Za-z0-9_-]{12,}\b/g, '[key]'],
102  [/\bgh[opusr]_[A-Za-z0-9]{12,}\b/g, '[key]'],
103  [/\bBearer\s+[A-Za-z0-9._~+/-]{12,}=*/g, 'Bearer [key]'],
104  [/\b(PIN|pin)(\s*[:=#]?\s*)\d{3,6}\b/g, '$1$2[pin]'],
105  [/\b[A-Za-z0-9+/]{48,}={0,2}(?![A-Za-z0-9+/=])/g, '[blob]'],
106];
107export function redactState<T>(value: T, counter = { n: 0 }): T {
108  if (typeof value === 'string') {
109    let out: string = value;
110    for (const [re, rep] of REDACTIONS) {
111      out = out.replace(re, (...m) => {
112        counter.n++;
113        return rep.replace('$1', String(m[1] ?? '')).replace('$2', String(m[2] ?? ''));
114      });
115    }
116    return out as unknown as T;
117  }
118  if (Array.isArray(value)) return value.map((v) => redactState(v, counter)) as unknown as T;
119  if (value && typeof value === 'object') {
120    const out: Record<string, unknown> = {};
121    for (const [k, v] of Object.entries(value as Record<string, unknown>)) out[k] = redactState(v, counter);
122    return out as T;
123  }
124  return value;
125}
126
127export const GATEWAY_URL = 'https://ai-gateway.vercel.sh/typesafe/v1/systemone';
128export const GATEWAY_MODEL = 'typesafe-ai/jev';
129
130export function jevAsker(fetchFn: HookFetch, apiKey: string, model: string, baseUrl?: string): JevAsker {
131  return {
132    async ask(state, questions) {
133      const request = buildJevRequest({ apiKey, model, baseUrl }, redactState(state), questions);
134      const response = await fetchFn(request.url, {
135        method: request.method,
136        headers: request.headers,
137        body: request.body,
138      });
139      return parseJevResponse(response.status, response.ok, response.text);
140    },
141  };
142}
143
144function toolUseSummary(tool: ToolUse): ToolUseSummary {
145  const summary: ToolUseSummary = {
146    tool_use_id: tool.tool_use_id,
147    tool: tool.tool,
148    input: tool.input,
149  };
150  if (tool.text !== undefined) summary.text = tool.text;
151  if (tool.isError) summary.isError = true;
152  return summary;
153}
154
155function toolResultSummary(result: ToolResult): ToolResultSummary {
156  return {
157    tool_use_id: result.tool_use_id,
158    text: result.text,
159    isError: result.isError ?? false,
160  };
161}
162
163/**
164 * Maps the library's output back onto session messages. Whatever came back
165 * unchanged (a message, a tool use, a tool result) is the engine's own object,
166 * handle included; anything rebuilt is a fresh message without a handle, so the
167 * engine takes the edited content instead of its original.
168 */
169export function toSessionMessages(
170  input: readonly SessionMessage[],
171  output: readonly Message[],
172): SessionMessage[] {
173  const messages = new Map<Message, SessionMessage>();
174  const uses = new Map<ToolUse, ToolUseSummary>();
175  const results = new Map<ToolResult, ToolResultSummary>();
176  for (const message of input) {
177    messages.set(message, message);
178    for (const tool of message.toolUses) uses.set(tool, tool);
179    for (const result of message.toolResults ?? []) results.set(result, result);
180  }
181  return output.map((message) => {
182    const own = messages.get(message);
183    if (own) return own;
184    const rebuilt: SessionMessage = {
185      role: message.role,
186      text: message.text,
187      toolUses: message.toolUses.map((tool) => uses.get(tool) ?? toolUseSummary(tool)),
188    };
189    if (message.toolResults && message.toolResults.length > 0) {
190      rebuilt.toolResults = message.toolResults.map(
191        (result) => results.get(result) ?? toolResultSummary(result),
192      );
193    }
194    return rebuilt;
195  });
196}
197
198export type SessionCompaction = {
199  result: CompactResult;
200  messages: SessionMessage[];
201};
202
203/** Runs the library over a session transcript; throws when the key is missing or Jev fails. */
204export async function compactSession(
205  messages: readonly SessionMessage[],
206  config: HookConfig,
207  fetchFn: HookFetch,
208): Promise<SessionCompaction> {
209  if (!config.apiKey) throw new Error('TYPESAFE_API_KEY is not configured');
210  const result = await compact(messages, jevAsker(fetchFn, config.apiKey, config.model, config.baseUrl), config);
211  return { result, messages: toSessionMessages(messages, result.messages) };
212}
213
214function percent(ratio: number): string {
215  return `${Math.round(ratio * 100)}%`;
216}
217
218export function summarize(result: CompactResult): string {
219  const { stats } = result;
220  const parts = [
221    stats.kept > 0 ? `${stats.kept} kept` : '',
222    stats.resultsDropped > 0 ? `${stats.resultsDropped} results truncated` : '',
223    stats.callsDropped > 0 ? `${stats.callsDropped} call_dropped` : '',
224    stats.pinned > 0 ? `${stats.pinned} pinned` : '',
225  ].filter(Boolean);
226  return `${percent(reductionRatio(result))} reduction; ${
227    parts.join(', ') || 'no tool calls'
228  }; state ~${stats.stateTokens} tokens (${stats.stateStage}) in ${stats.requests} request(s)`;
229}
230
231const UI_LOG_MAX_CHARS = 4096;
232
233export function decisionLog(result: CompactResult): string {
234  return result.decisions
235    .filter((d) => d.reason !== 'pinned')
236    .map(
237      (d) =>
238        `${d.id}:${d.tool}:${d.action}/call=${d.keepCall.toFixed(2)}/result=${d.keepResult.toFixed(2)}`,
239    )
240    .join(' ');
241}
242
243export function decisionLogLines(
244  result: CompactResult,
245  maxChars: number = UI_LOG_MAX_CHARS,
246): string[] {
247  const entries = decisionLog(result).split(' ').filter(Boolean);
248  if (entries.length === 0) return ['decisions: (none)'];
249  const chunks: string[] = [];
250  let current = '';
251  for (const entry of entries) {
252    const next = current ? `${current} ${entry}` : entry;
253    if (current && next.length > maxChars - 24) {
254      chunks.push(current);
255      current = entry;
256    } else current = next;
257  }
258  chunks.push(current);
259  return chunks.map((chunk, index) =>
260    chunks.length === 1
261      ? `decisions: ${chunk}`
262      : `decisions (${index + 1}/${chunks.length}): ${chunk}`,
263  );
264}
265
266async function getApiKey(
267  $: {
268    env: { get: (name: string) => Promise<string | undefined> };
269    settings: { read: () => Promise<Readonly<Record<string, unknown>>> };
270  },
271  config: HookConfig,
272): Promise<string | undefined> {
273  return (await resolveEndpoint($, config)).apiKey;
274}
275
276/* JFC fork: TYPESAFE_API_KEY keeps the upstream endpoint. Without it, JFC's
277   budget-capped Vercel key (AI_GATEWAY_API_KEY, USD 1, alerts on) routes the
278   same request through Vercel's TypeSafe-compatible API. No key -> nothing is
279   sent and Claude Code's normal summary runs. */
280export async function resolveEndpoint(
281  $: {
282    env: { get: (name: string) => Promise<string | undefined> };
283    settings: { read: () => Promise<Readonly<Record<string, unknown>>> };
284  },
285  config: HookConfig,
286): Promise<{ apiKey?: string; baseUrl?: string; model?: string }> {
287  if (config.apiKey) return { apiKey: config.apiKey };
288  const settings = await $.settings.read();
289  const env = settings['env'] && typeof settings['env'] === 'object' ? (settings['env'] as Record<string, unknown>) : {};
290  /* 2026-09-26 (friendly-123, nube): Claude Code exige que $.env.get reciba un nombre
291     LITERAL (asi puede listar que variables lee el modulo). La version anterior pasaba
292     una variable y el plugin no pasaba la validacion: nunca llegaba a cargar. */
293  const desdeSettings = (name: string) => {
294    const value = env[name];
295    return typeof value === 'string' && value ? value : undefined;
296  };
297  const typesafe = (await $.env.get('TYPESAFE_API_KEY')) || desdeSettings('TYPESAFE_API_KEY');
298  if (typesafe) return { apiKey: typesafe };
299  const gateway = (await $.env.get('AI_GATEWAY_API_KEY')) || desdeSettings('AI_GATEWAY_API_KEY');
300  if (gateway) return { apiKey: gateway, baseUrl: GATEWAY_URL, model: GATEWAY_MODEL };
301  return {};
302}
303
304function notify(
305  $: {
306    ui: {
307      log: (text: string) => void;
308      toast: (text: string, options?: { timeoutMs?: number }) => void;
309    };
310  },
311  text: string,
312): void {
313  $.ui.log(text);
314  $.ui.toast(text, { timeoutMs: 15_000 });
315}
316
317export const register: Register = (on: On, options: PluginOptions) => {
318  const configured = resolveHookConfig(options);
319  let compacting = false;
320
321  on('session.compact', async ($, event, next) => {
322    try {
323      const endpoint = await resolveEndpoint($, configured);
324      const config = {
325        ...configured,
326        apiKey: endpoint.apiKey,
327        ...(endpoint.baseUrl ? { baseUrl: endpoint.baseUrl, model: endpoint.model ?? configured.model } : {}),
328      };
329      const { result, messages } = await compactSession(event.messages, config, async (url, init) => {
330        const response = await $.http.fetch(url, init);
331        return { status: response.status, ok: response.ok, text: response.text };
332      });
333      for (const line of decisionLogLines(result)) $.ui.log(line);
334      if (reductionRatio(result) < config.minReductionRatio) {
335        notify(
336          $,
337          `fallback to built-in summary (below ${percent(config.minReductionRatio)} minimum: ${summarize(result)})`,
338        );
339        return next(event);
340      }
341      notify(
342        $,
343        `kept ${messages.length}/${event.messages.length} messages, no summary (${summarize(result)})`,
344      );
345      return { messages };
346    } catch (error) {
347      notify(
348        $,
349        `fallback to built-in summary (${error instanceof Error ? error.message : String(error)})`,
350      );
351      return next(event);
352    }
353  });
354
355  on('turn.complete', async ($, event: TurnCompleteInput, next) => {
356    if (compacting) return next(event);
357    try {
358      const { context } = await $.session.usage();
359      if ((context.percent ?? 0) < configured.compactAtPercent) return next(event);
360      compacting = true;
361      await $.session.compact();
362    } catch (error) {
363      $.ui.log(
364        `auto-compact skipped (${error instanceof Error ? error.message : String(error)})`,
365      );
366    } finally {
367      compacting = false;
368    }
369    return next(event);
370  });
371};
372
373export { resolveOptions };
374

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