@alexlikevibe/pi-jev 0.2.0

package/src/vendor/fast-jev-compaction/request.ts

@@ -0,0 +1,80 @@
+import type { JevAnswer, JevQuestions, JevResponse, JevState } from './types.js';
+
+export const SYSTEM_ONE_URL = 'https://api.typesafe.ai/v1/systemone';
+export const DEFAULT_MODEL = 'jev-latest';
+
+export interface JevRequest {
+  url: string;
+  method: 'POST';
+  headers: Record<string, string>;
+  body: string;
+}
+
+/** The HTTP request for one Jev call, for any fetch-like transport. */
+export function buildJevRequest(
+  params: {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+  },
+  state: JevState,
+  questions: JevQuestions,
+): JevRequest {
+  return {
+    url: params.baseUrl ?? SYSTEM_ONE_URL,
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${params.apiKey}`,
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify({
+      model: params.model ?? DEFAULT_MODEL,
+      state,
+      questions,
+    }),
+  };
+}
+
+/** Validates a Jev response body; throws on anything but an `answers` object. */
+export function parseJevResponse(
+  status: number,
+  ok: boolean,
+  text: string,
+): JevResponse {
+  if (!ok) {
+    throw new Error(`Jev request failed (${status}): ${text.slice(0, 200)}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error('Jev returned malformed JSON');
+  }
+  if (
+    parsed === null ||
+    typeof parsed !== 'object' ||
+    !('answers' in parsed) ||
+    parsed.answers === null ||
+    typeof parsed.answers !== 'object'
+  ) {
+    throw new Error('Jev response is missing answers');
+  }
+  return parsed as JevResponse;
+}
+
+/** The `noul` probability of one answer; throws when it is not there. */
+export function noulAnswer(
+  answers: Record<string, JevAnswer>,
+  name: string,
+): number {
+  const answer = answers[name];
+  if (
+    !answer ||
+    !('noul' in answer) ||
+    typeof answer.noul !== 'number' ||
+    !Number.isFinite(answer.noul)
+  ) {
+    throw new Error(`Invalid Jev answer for ${name}`);
+  }
+  return answer.noul;
+}

package/src/vendor/fast-jev-compaction/state.ts

@@ -0,0 +1,304 @@
+import type {
+  CompactionState,
+  FittedState,
+  HistoryEntry,
+  Message,
+  ResolvedCompactOptions,
+  ToolCall,
+  ToolResult,
+} from './types.js';
+
+export const STATE_CONTEXT =
+  '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.';
+
+/** Successive caps on the serialised tool input included per call. */
+const INPUT_CHARS = [1000, 200, 60] as const;
+const TEXT_HEAD = 400;
+const TEXT_TAIL = 150;
+
+const TOKEN_PIECES = /[A-Za-z]+|\d+|[^\sA-Za-z\d]/g;
+
+/**
+ * Estimates tokens without a tokenizer: a word costs one token per six
+ * letters, a digit half a token, any other symbol nine tenths. Calibrated
+ * against the usage Jev reports for real transcripts, where it lands 2–18%
+ * above the true count; a plain characters-per-token ratio undercounts the
+ * JSON-heavy states by up to 40%.
+ */
+export function estimateTokens(text: string): number {
+  let tokens = 0;
+  for (const [piece] of text.matchAll(TOKEN_PIECES)) {
+    const first = piece.charCodeAt(0);
+    if (first >= 48 && first <= 57) tokens += piece.length / 2;
+    else if ((first >= 65 && first <= 90) || (first >= 97 && first <= 122)) {
+      tokens += 1 + Math.floor((piece.length - 1) / 6);
+    } else tokens += 0.9;
+  }
+  return Math.ceil(tokens);
+}
+
+export function truncate(text: string, limit: number): string {
+  return text.length <= limit ? text : `${text.slice(0, Math.max(0, limit - 1))}…`;
+}
+
+function abridge(text: string, head: number, tail: number): string {
+  if (text.length <= head + tail + 40) return text;
+  const omitted = text.length - head - tail;
+  return `${text.slice(0, head)}\n[… ${omitted} chars omitted …]\n${text.slice(-tail)}`;
+}
+
+export function isPinned(
+  index: number,
+  total: number,
+  preserveRecentMessages: number,
+): boolean {
+  return index === 0 || index >= total - preserveRecentMessages;
+}
+
+/**
+ * Pairs every tool_use with its tool_result by `tool_use_id`. Calls without a
+ * result are not candidates (there is nothing to drop yet).
+ */
+export function collectToolCalls(
+  messages: readonly Message[],
+  preserveRecentMessages: number,
+): ToolCall[] {
+  const results = new Map<string, { index: number; result: ToolResult }>();
+  messages.forEach((message, index) => {
+    for (const result of message.toolResults ?? []) {
+      results.set(result.tool_use_id, { index, result });
+    }
+  });
+  const calls: ToolCall[] = [];
+  messages.forEach((message, callIndex) => {
+    for (const tool of message.toolUses) {
+      const found = results.get(tool.tool_use_id);
+      if (!found) continue;
+      calls.push({
+        id: `t${calls.length + 1}`,
+        tool_use_id: tool.tool_use_id,
+        tool: tool.tool,
+        input: tool.input,
+        callIndex,
+        resultIndex: found.index,
+        resultChars: found.result.text.length,
+        isError: found.result.isError ?? false,
+        pinned:
+          isPinned(callIndex, messages.length, preserveRecentMessages) ||
+          isPinned(found.index, messages.length, preserveRecentMessages),
+      });
+    }
+  });
+  return calls;
+}
+
+function inputText(input: Record<string, unknown>, limit: number): string {
+  let json = '';
+  try {
+    json = JSON.stringify(input);
+  } catch {
+    json = '[unserializable input]';
+  }
+  return truncate(json, limit);
+}
+
+function resultNote(call: ToolCall): string {
+  return `${call.isError ? 'error' : 'ok'}, ${call.resultChars} chars (omitted)`;
+}
+
+/** One call as a single line, for when the structured form is too costly. */
+function compactCall(call: ToolCall): string {
+  const input = Object.entries(call.input)
+    .map(([key, value]) => {
+      const text = typeof value === 'string' ? value : inputText({ [key]: value }, 200);
+      return `${key}=${text.replace(/\s+/g, ' ')}`;
+    })
+    .join(' ');
+  return `${call.id} ${call.tool} ${truncate(input, INPUT_CHARS[2])} → ${
+    call.isError ? 'error' : 'ok'
+  } ${call.resultChars}ch`;
+}
+
+/**
+ * Folds runs of adjacent call-only entries into one entry each, so the
+ * per-entry envelope is paid once per run; the call lines keep their ids.
+ */
+function mergeCallRuns(history: readonly HistoryEntry[], pinned: (e: HistoryEntry) => boolean): HistoryEntry[] {
+  const merged: HistoryEntry[] = [];
+  for (const entry of history) {
+    const previous = merged[merged.length - 1];
+    const foldable = (e: HistoryEntry): boolean =>
+      !pinned(e) && e.text.length === 0 && typeof e.tool_calls?.[0] === 'string';
+    if (previous && foldable(previous) && foldable(entry) && previous.role === entry.role) {
+      previous.tool_calls = [...(previous.tool_calls as string[]), ...(entry.tool_calls as string[])];
+      continue;
+    }
+    merged.push({ ...entry });
+  }
+  return merged;
+}
+
+function callsByMessage(calls: readonly ToolCall[]): Map<number, ToolCall[]> {
+  const byMessage = new Map<number, ToolCall[]>();
+  for (const call of calls) {
+    const list = byMessage.get(call.callIndex) ?? [];
+    list.push(call);
+    byMessage.set(call.callIndex, list);
+  }
+  return byMessage;
+}
+
+function historyEntries(
+  messages: readonly Message[],
+  calls: readonly ToolCall[],
+  inputChars: number,
+): HistoryEntry[] {
+  const byMessage = callsByMessage(calls);
+  const entries: HistoryEntry[] = [];
+  messages.forEach((message, i) => {
+    const toolCalls = (byMessage.get(i) ?? []).map((call) => ({
+      id: call.id,
+      tool: call.tool,
+      input: inputText(call.input, inputChars),
+      result: resultNote(call),
+    }));
+    if (message.text.trim().length === 0 && toolCalls.length === 0) return;
+    const entry: HistoryEntry = { i, role: message.role, text: message.text };
+    if (toolCalls.length > 0) entry.tool_calls = toolCalls;
+    entries.push(entry);
+  });
+  return entries;
+}
+
+/** The last three user prompts, as the default `goal`. */
+export function goalFromMessages(messages: readonly Message[]): string {
+  return messages
+    .filter(
+      (message) =>
+        message.role === 'user' &&
+        message.text.trim().length > 0 &&
+        (message.toolResults ?? []).length === 0,
+    )
+    .slice(-3)
+    .map((message) => truncate(message.text, 500))
+    .join('\n');
+}
+
+/**
+ * Builds the Jev state from the whole conversation and shrinks it in stages
+ * until it fits `maxStateTokens`: tool inputs are truncated, then long texts
+ * are abridged oldest-first (pinned messages last), then old messages collapse
+ * to a one-line note, then old tool calls shrink to one line each, then old
+ * messages that carry no call are left out, then runs of old call-only
+ * messages are folded into one entry. Throws when even that is too big.
+ */
+export function fitState(
+  messages: readonly Message[],
+  calls: readonly ToolCall[],
+  options: Pick<ResolvedCompactOptions, 'maxStateTokens' | 'preserveRecentMessages' | 'goal'>,
+): FittedState {
+  const goal = options.goal || goalFromMessages(messages);
+  const stateOf = (history: HistoryEntry[]): CompactionState => ({
+    context: STATE_CONTEXT,
+    goal,
+    history,
+  });
+  const entryTokens = (entry: HistoryEntry): number => estimateTokens(JSON.stringify(entry)) + 1;
+  const baseTokens = estimateTokens(JSON.stringify(stateOf([])));
+  const fitted = (history: HistoryEntry[], tokens: number, stage: string): FittedState => ({
+    state: stateOf(history),
+    tokens,
+    stage,
+  });
+
+  let history: HistoryEntry[] = [];
+  let perEntry: number[] = [];
+  let tokens = 0;
+  const rebuild = (inputChars: number): void => {
+    history = historyEntries(messages, calls, inputChars);
+    perEntry = history.map(entryTokens);
+    tokens = baseTokens + perEntry.reduce((sum, n) => sum + n, 0);
+  };
+  const fits = (): boolean => tokens <= options.maxStateTokens;
+  const shrink = (index: number, change: (entry: HistoryEntry) => void): void => {
+    const entry = history[index];
+    if (!entry) return;
+    change(entry);
+    const now = entryTokens(entry);
+    tokens += now - (perEntry[index] ?? 0);
+    perEntry[index] = now;
+  };
+
+  rebuild(INPUT_CHARS[0]);
+  if (fits()) return fitted(history, tokens, 'full');
+
+  for (const limit of INPUT_CHARS.slice(1)) {
+    rebuild(limit);
+    if (fits()) return fitted(history, tokens, `inputs<=${limit}`);
+  }
+
+  const pinned = (entry: HistoryEntry): boolean =>
+    isPinned(entry.i, messages.length, options.preserveRecentMessages);
+  const indices = history.map((_, index) => index);
+  const order = [
+    ...indices.filter((index) => !pinned(history[index]!)),
+    ...indices.filter((index) => pinned(history[index]!)),
+  ];
+
+  for (const index of order) {
+    const entry = history[index]!;
+    if (entry.text.length <= TEXT_HEAD + TEXT_TAIL + 40) continue;
+    shrink(index, (e) => {
+      e.text = abridge(e.text, TEXT_HEAD, TEXT_TAIL);
+    });
+    if (fits()) return fitted(history, tokens, 'texts abridged');
+  }
+
+  for (const index of order) {
+    const entry = history[index]!;
+    if (pinned(entry) || entry.text.length === 0) continue;
+    const original = messages[entry.i]?.text.length ?? entry.text.length;
+    shrink(index, (e) => {
+      e.text = `[… ${original} chars omitted …]`;
+    });
+    if (fits()) return fitted(history, tokens, 'old messages collapsed');
+  }
+
+  const byMessage = callsByMessage(calls);
+  for (const index of order) {
+    const entry = history[index]!;
+    const own = byMessage.get(entry.i);
+    if (pinned(entry) || !own) continue;
+    shrink(index, (e) => {
+      e.tool_calls = own.map(compactCall);
+    });
+    if (fits()) return fitted(history, tokens, 'old calls compacted');
+  }
+
+  const left = new Set<number>();
+  for (const index of order) {
+    const entry = history[index]!;
+    if (pinned(entry) || entry.tool_calls) continue;
+    left.add(index);
+    tokens -= perEntry[index] ?? 0;
+    if (fits()) {
+      return fitted(
+        history.filter((_, i) => !left.has(i)),
+        tokens,
+        'old messages left out',
+      );
+    }
+  }
+
+  history = mergeCallRuns(
+    history.filter((_, i) => !left.has(i)),
+    pinned,
+  );
+  perEntry = history.map(entryTokens);
+  tokens = baseTokens + perEntry.reduce((sum, n) => sum + n, 0);
+  if (fits()) return fitted(history, tokens, 'old calls merged');
+
+  throw new Error(
+    `history too large for Jev (~${tokens} tokens after truncation, limit ${options.maxStateTokens})`,
+  );
+}

package/src/vendor/fast-jev-compaction/types.ts

@@ -0,0 +1,202 @@
+export type Role = 'user' | 'assistant';
+
+/**
+ * A tool_use block of an assistant message. `text` and `isError` mirror the
+ * outcome once the transcript holds it (Claude Code attaches them).
+ */
+export interface ToolUse {
+  tool_use_id: string;
+  tool: string;
+  input: Record<string, unknown>;
+  text?: string;
+  isError?: boolean;
+}
+
+/** A tool_result block of a user message. */
+export interface ToolResult {
+  tool_use_id: string;
+  text: string;
+  isError?: boolean;
+}
+
+/**
+ * One transcript message. The shape is a subset of Claude Code's
+ * `SessionMessage`, so a session transcript can be passed in as is.
+ */
+export interface Message {
+  role: Role;
+  text: string;
+  toolUses: ToolUse[];
+  toolResults?: ToolResult[];
+}
+
+/** A tool call paired with its result by `tool_use_id`. */
+export interface ToolCall {
+  /** Short id used in the Jev state and question names (`t1`, `t2`, ...). */
+  id: string;
+  tool_use_id: string;
+  tool: string;
+  input: Record<string, unknown>;
+  /** Index of the message holding the tool_use block. */
+  callIndex: number;
+  /** Index of the message holding the tool_result block. */
+  resultIndex: number;
+  resultChars: number;
+  isError: boolean;
+  /** In the first or the newest preserved messages; never a candidate. */
+  pinned: boolean;
+}
+
+export interface CallAnswer {
+  /** Jev's probability that the call itself still matters. */
+  keepCall: number;
+  /** Jev's probability that the full result still needs to stay verbatim. */
+  keepResult: number;
+}
+
+export type CallAction = 'keep' | 'drop_result' | 'drop_call';
+
+export interface CallDecision extends CallAnswer {
+  id: string;
+  tool: string;
+  action: CallAction;
+  reason: 'pinned' | 'kept' | 'result_dropped' | 'call_dropped';
+}
+
+export interface HistoryToolCall {
+  id: string;
+  tool: string;
+  input: string;
+  result: string;
+}
+
+export interface HistoryEntry {
+  i: number;
+  role: Role;
+  text: string;
+  /** Structured per call, or one compact line per call once the state has to shrink. */
+  tool_calls?: HistoryToolCall[] | string[];
+}
+
+/** The state sent with every Jev request: the whole history, results omitted. */
+export interface CompactionState {
+  context: string;
+  goal: string;
+  history: HistoryEntry[];
+}
+
+export interface FittedState {
+  state: CompactionState;
+  tokens: number;
+  /** Which fitting stage produced the state, for diagnostics. */
+  stage: string;
+}
+
+export interface CompactOptions {
+  /** Ongoing task description; defaults to the last few user prompts. */
+  goal?: string;
+  /** Minimum keep probability for a call or result to stay. Default 0.5. */
+  keepThreshold?: number;
+  /** Newest messages never touched (the first message is always kept). Default 6. */
+  preserveRecentMessages?: number;
+  /** Estimated token ceiling for the state. Default 25000. */
+  maxStateTokens?: number;
+  /** Estimated token ceiling for state plus one batch of questions. Default 30000. */
+  maxRequestTokens?: number;
+  /** Characters of a dropped tool result to retain. Default 300. */
+  truncateHeadChars?: number;
+}
+
+export interface ResolvedCompactOptions {
+  goal: string;
+  keepThreshold: number;
+  preserveRecentMessages: number;
+  maxStateTokens: number;
+  maxRequestTokens: number;
+  truncateHeadChars: number;
+}
+
+export interface CompactResult {
+  /** The compacted transcript; untouched messages are the input objects. */
+  messages: Message[];
+  decisions: CallDecision[];
+  stats: {
+    messagesBefore: number;
+    messagesAfter: number;
+    charsBefore: number;
+    charsAfter: number;
+    calls: number;
+    kept: number;
+    resultsDropped: number;
+    callsDropped: number;
+    pinned: number;
+    stateTokens: number;
+    /** Which fitting stage the state needed, '' when no request was made. */
+    stateStage: string;
+    requests: number;
+    ms: number;
+  };
+}
+
+/** The `state` of a Jev request: a string or any JSON-serialisable object. */
+export type JevState = string | object;
+
+export interface NoulQuestion {
+  type: 'noul';
+  instructions: string;
+  criteria?: {
+    true?: string;
+    false?: string;
+  };
+}
+
+export interface ChoiceQuestion {
+  type: 'choice';
+  instructions: string;
+  criteria: Record<string, string | null>;
+}
+
+export interface ScoreQuestion {
+  type: 'score';
+  instructions: string;
+  criteria: string[];
+}
+
+export type JevQuestion = NoulQuestion | ChoiceQuestion | ScoreQuestion;
+export type JevQuestions = Record<string, JevQuestion>;
+
+export interface NoulAnswer {
+  type?: 'noul';
+  noul: number;
+}
+
+export interface ChoiceAnswer {
+  type?: 'choice';
+  choice: string;
+  confidence: number;
+  probabilities: Record<string, number>;
+}
+
+export interface ScoreAnswer {
+  type?: 'score';
+  score: number;
+  confidence: number;
+  probabilities: Record<string, number>;
+}
+
+export type JevAnswer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
+
+export interface JevResponse {
+  model?: string;
+  answers: Record<string, JevAnswer>;
+  usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+  };
+  [key: string]: unknown;
+}
+
+/** Anything that can answer Jev questions: `JevClient`, or a host-provided adapter. */
+export interface JevAsker {
+  ask(state: JevState, questions: JevQuestions): Promise<JevResponse>;
+}