theus-cli 0.2.83 → 0.2.85

package/vendor/theus-arsenal/scripts/lib/transcript-context.js

@@ -1,232 +0,0 @@
-/**
- * Helpers de tamaño de contexto de la transcripción para el hook de
- * compactación estratégica.
- *
- * Lee el registro `usage` del asistente más reciente de una transcripción de
- * sesión de Theus (JSONL, en `~/.theus/projects/<dir-escapado>/<session_id>.jsonl`;
- * los hooks reciben la ruta en el campo `transcript_path` del stdin) y deriva
- * una señal de tamaño de contexto:
- *
- * - `input_tokens + cache_read_input_tokens + cache_creation_input_tokens`
- *   particionan el prompt, así que su suma es el tamaño de contexto real del turno.
- * - La ventana de contexto se detecta a partir del id del modelo (marcador
- *   `[1m]`) o del conteo de tokens observado (cualquier valor por encima de
- *   200k implica una ventana de 1M incluso cuando los logs omiten el sufijo).
- * - Los umbrales escalan con la ventana y se pueden anular por variables de
- *   entorno; los recordatorios repetidos se disparan en "cubetas" fijas de
- *   tokens por encima del umbral, de modo que la sugerencia solo se repite
- *   tras un crecimiento real del contexto.
- *
- * Solo se lee la cola de la transcripción (los registros más recientes viven
- * al final), manteniendo el hook PreToolUse rápido incluso para sesiones muy
- * grandes.
- */
-
-const fs = require('fs');
-
-const STANDARD_CONTEXT_WINDOW_TOKENS = 200000;
-const LARGE_CONTEXT_WINDOW_TOKENS = 1000000;
-const DEFAULT_CONTEXT_THRESHOLD_STANDARD = 160000;
-const DEFAULT_CONTEXT_THRESHOLD_LARGE = 250000;
-const DEFAULT_CONTEXT_INTERVAL_TOKENS = 60000;
-const DEFAULT_TRANSCRIPT_TAIL_BYTES = 256 * 1024;
-const MAX_TOKEN_SETTING = 10000000;
-const LARGE_WINDOW_MODEL_MARKER = '[1m]';
-
-/**
- * Lee los últimos `tailBytes` de un archivo como UTF-8.
- * Devuelve null cuando el archivo no existe o no se puede leer.
- */
-function readFileTail(filePath, tailBytes) {
-  let fd;
-  try {
-    fd = fs.openSync(filePath, 'r');
-  } catch {
-    return null;
-  }
-
-  try {
-    const size = fs.fstatSync(fd).size;
-    const start = Math.max(0, size - tailBytes);
-    const length = size - start;
-    if (length <= 0) {
-      return { text: '', truncated: false };
-    }
-
-    const buffer = Buffer.alloc(length);
-    const bytesRead = fs.readSync(fd, buffer, 0, length, start);
-    return {
-      text: buffer.toString('utf8', 0, bytesRead),
-      truncated: start > 0
-    };
-  } catch {
-    return null;
-  } finally {
-    try {
-      fs.closeSync(fd);
-    } catch {
-      /* ignorar */
-    }
-  }
-}
-
-/**
- * Extrae el total de tokens de contexto del bloque usage de un registro de la
- * transcripción. Devuelve 0 cuando el registro no trae datos de uso utilizables.
- */
-function extractUsageTokens(record) {
-  const usage = record && record.message && record.message.usage;
-  if (!usage || typeof usage !== 'object') {
-    return 0;
-  }
-
-  const total =
-    (Number.isFinite(usage.input_tokens) ? usage.input_tokens : 0) +
-    (Number.isFinite(usage.cache_read_input_tokens) ? usage.cache_read_input_tokens : 0) +
-    (Number.isFinite(usage.cache_creation_input_tokens) ? usage.cache_creation_input_tokens : 0);
-
-  return total > 0 ? total : 0;
-}
-
-/**
- * Escanea una transcripción de sesión (JSONL) hacia atrás en busca del
- * registro más reciente con un bloque `message.usage` no vacío.
- *
- * @param {string} transcriptPath - Ruta absoluta de la transcripción JSONL.
- * @param {object} [options]
- * @param {number} [options.tailBytes] - Cuántos bytes finales escanear.
- * @returns {{ tokens: number, model: string } | null} Tamaño de contexto más
- *   reciente, o null cuando la transcripción no existe, no se puede leer o no
- *   tiene registros de uso.
- */
-function readLatestContextTokens(transcriptPath, options = {}) {
-  if (typeof transcriptPath !== 'string' || !transcriptPath) {
-    return null;
-  }
-
-  const tailBytes = Number.isInteger(options.tailBytes) && options.tailBytes > 0 ? options.tailBytes : DEFAULT_TRANSCRIPT_TAIL_BYTES;
-
-  const tail = readFileTail(transcriptPath, tailBytes);
-  if (!tail) {
-    return null;
-  }
-
-  const lines = tail.text.split('\n');
-  // La primera línea de una cola truncada es casi con seguridad JSON parcial.
-  const firstLine = tail.truncated ? 1 : 0;
-
-  for (let i = lines.length - 1; i >= firstLine; i--) {
-    const line = lines[i].trim();
-    if (!line) continue;
-
-    let record;
-    try {
-      record = JSON.parse(line);
-    } catch {
-      continue;
-    }
-
-    const tokens = extractUsageTokens(record);
-    if (tokens > 0) {
-      const model = record.message && typeof record.message.model === 'string' ? record.message.model : '';
-      return { tokens, model };
-    }
-  }
-
-  return null;
-}
-
-/**
- * Detecta el tamaño de la ventana de contexto de un turno.
- * 1M cuando el id del modelo lleva el marcador `[1m]`, o cuando el conteo de
- * tokens observado ya excede la ventana estándar de 200k (cubre logs que
- * omiten el sufijo); en caso contrario, la ventana estándar de 200k.
- */
-function resolveContextWindowTokens(tokens, model) {
-  // Un override explícito de ventana gana: los modelos con ventanas intermedias
-  // (p. ej. 400k) no coinciden ni con el estándar de 200k ni con el marcador de
-  // 1M, y de otro modo reportarían aproximadamente el doble de uso.
-  const env = (typeof process !== 'undefined' && process.env) || {};
-  const envWindow = Number.parseInt(env.THEUS_CONTEXT_WINDOW_TOKENS || '', 10);
-  if (Number.isInteger(envWindow) && envWindow > 0) {
-    return envWindow;
-  }
-
-  if (typeof model === 'string' && model.includes(LARGE_WINDOW_MODEL_MARKER)) {
-    return LARGE_CONTEXT_WINDOW_TOKENS;
-  }
-
-  if (Number.isFinite(tokens) && tokens > STANDARD_CONTEXT_WINDOW_TOKENS) {
-    return LARGE_CONTEXT_WINDOW_TOKENS;
-  }
-
-  return STANDARD_CONTEXT_WINDOW_TOKENS;
-}
-
-/**
- * Resuelve el umbral (en tokens) para la sugerencia por tamaño de contexto.
- * `COMPACT_CONTEXT_THRESHOLD=0` desactiva por completo la señal de contexto;
- * otros valores inválidos caen al valor por defecto escalado por ventana.
- */
-function resolveContextThreshold(env, windowTokens) {
-  const raw = env && env.COMPACT_CONTEXT_THRESHOLD;
-  if (raw !== undefined && raw !== null && raw !== '') {
-    const parsed = Number.parseInt(raw, 10);
-    if (parsed === 0) {
-      return 0;
-    }
-    if (Number.isInteger(parsed) && parsed > 0 && parsed <= MAX_TOKEN_SETTING) {
-      return parsed;
-    }
-  }
-
-  return windowTokens >= LARGE_CONTEXT_WINDOW_TOKENS ? DEFAULT_CONTEXT_THRESHOLD_LARGE : DEFAULT_CONTEXT_THRESHOLD_STANDARD;
-}
-
-/**
- * Resuelve el paso de recordatorio (tokens de crecimiento adicional de
- * contexto antes de repetir la sugerencia). Los valores inválidos caen al
- * valor por defecto.
- */
-function resolveContextInterval(env) {
-  const raw = env && env.COMPACT_CONTEXT_INTERVAL;
-  const parsed = Number.parseInt(raw, 10);
-  return Number.isInteger(parsed) && parsed > 0 && parsed <= MAX_TOKEN_SETTING ? parsed : DEFAULT_CONTEXT_INTERVAL_TOKENS;
-}
-
-/**
- * Mapea un tamaño de contexto a una cubeta de sugerencia.
- * Devuelve -1 por debajo del umbral; cubeta 0 en el umbral; +1 por cada
- * `interval` tokens de crecimiento adicional. El hook se dispara solo cuando
- * la cubeta sube por encima de la última cubeta para la que ya se disparó.
- */
-function computeContextBucket(tokens, threshold, interval) {
-  if (!Number.isFinite(tokens) || threshold <= 0 || tokens < threshold) {
-    return -1;
-  }
-
-  const step = Number.isInteger(interval) && interval > 0 ? interval : DEFAULT_CONTEXT_INTERVAL_TOKENS;
-  return Math.floor((tokens - threshold) / step);
-}
-
-/**
- * Etiqueta legible para un tamaño de ventana de contexto (p. ej. "200k", "1M").
- */
-function formatWindowLabel(windowTokens) {
-  return windowTokens >= LARGE_CONTEXT_WINDOW_TOKENS ? '1M' : `${Math.round(windowTokens / 1000)}k`;
-}
-
-module.exports = {
-  STANDARD_CONTEXT_WINDOW_TOKENS,
-  LARGE_CONTEXT_WINDOW_TOKENS,
-  DEFAULT_CONTEXT_THRESHOLD_STANDARD,
-  DEFAULT_CONTEXT_THRESHOLD_LARGE,
-  DEFAULT_CONTEXT_INTERVAL_TOKENS,
-  DEFAULT_TRANSCRIPT_TAIL_BYTES,
-  readLatestContextTokens,
-  resolveContextWindowTokens,
-  resolveContextThreshold,
-  resolveContextInterval,
-  computeContextBucket,
-  formatWindowLabel
-};

package/vendor/theus-arsenal/scripts/lib/utils.d.ts

@@ -1,205 +0,0 @@
-/**
- * Funciones utilitarias multiplataforma para hooks y scripts de Theus.
- * Funciona en Windows, macOS y Linux.
- */
-
-import type { ExecSyncOptions } from 'child_process';
-
-// Detección de plataforma
-export const isWindows: boolean;
-export const isMacOS: boolean;
-export const isLinux: boolean;
-
-// --- Directorios ---
-
-/** Obtiene el directorio home del usuario (multiplataforma) */
-export function getHomeDir(): string;
-
-/**
- * Raíz de datos del agente Theus para persistencia de memoria y estado.
- * Orden: THEUS_AGENT_DATA_HOME → ~/.theus/arsenal por defecto (estable en
- * todos los contextos de ejecución; ver scripts/lib/agent-data-home.js).
- */
-export function getAgentDataHome(): string;
-
-/** Obtiene el directorio de datos del agente (alias de getAgentDataHome) */
-export function getTheusDir(): string;
-
-/** Obtiene el directorio canónico de sesiones ($THEUS_AGENT_DATA_HOME/session-data) */
-export function getSessionsDir(): string;
-
-/** Obtiene el directorio de sesiones heredado ($THEUS_AGENT_DATA_HOME/sessions) */
-export function getLegacySessionsDir(): string;
-
-/** Obtiene los directorios de sesiones a explorar: primero el canónico, luego el heredado */
-export function getSessionSearchDirs(): string[];
-
-/** Obtiene el directorio de skills aprendidas ($THEUS_AGENT_DATA_HOME/skills/learned) */
-export function getLearnedSkillsDir(): string;
-
-/** Obtiene el directorio temporal (multiplataforma) */
-export function getTempDir(): string;
-
-/**
- * Garantiza que un directorio exista, creándolo recursivamente si es necesario.
- * Maneja condiciones de carrera EEXIST por creación concurrente.
- * @throws Si el directorio no puede crearse (p. ej., permiso denegado)
- */
-export function ensureDir(dirPath: string): string;
-
-// --- Fecha/Hora ---
-
-/** Obtiene la fecha actual en formato YYYY-MM-DD */
-export function getDateString(): string;
-
-/** Obtiene la hora actual en formato HH:MM */
-export function getTimeString(): string;
-
-/** Obtiene la fecha y hora actuales en formato YYYY-MM-DD HH:MM:SS */
-export function getDateTimeString(): string;
-
-// --- Sesión/Proyecto ---
-
-/**
- * Sanitiza una cadena para usarla como segmento de nombre de archivo de sesión.
- * Reemplaza caracteres inválidos, quita puntos iniciales y devuelve null cuando
- * no queda nada significativo. Los nombres no ASCII se hashean por estabilidad.
- */
-export function sanitizeSessionId(raw: string | null | undefined): string | null;
-
-/**
- * Obtiene el id corto de sesión a partir del `session_id` que el motor Theus
- * entrega a los hooks por stdin (JSON); pásalo como segundo argumento.
- * Devuelve los últimos 8 caracteres; cae al nombre sanitizado del proyecto y
- * luego al valor de respaldo indicado.
- */
-export function getSessionIdShort(fallback?: string, sessionId?: string): string;
-
-/** Obtiene el nombre del repositorio git desde el directorio de trabajo actual */
-export function getGitRepoName(): string | null;
-
-/** Obtiene el nombre del proyecto desde el repo git o el nombre del directorio actual */
-export function getProjectName(): string | null;
-
-// --- Operaciones con archivos ---
-
-export interface FileMatch {
-  /** Ruta absoluta del archivo coincidente */
-  path: string;
-  /** Fecha de modificación en milisegundos desde la época */
-  mtime: number;
-}
-
-export interface FindFilesOptions {
-  /** Antigüedad máxima en días. Solo se devuelven archivos modificados dentro de ese lapso. */
-  maxAge?: number | null;
-  /** Si se deben explorar subdirectorios recursivamente */
-  recursive?: boolean;
-}
-
-/**
- * Busca archivos que coincidan con un patrón tipo glob en un directorio.
- * Admite `*` (cualquier secuencia), `?` (un carácter) y `.` (punto literal).
- * Los resultados se ordenan por fecha de modificación (más reciente primero).
- */
-export function findFiles(dir: string, pattern: string, options?: FindFilesOptions): FileMatch[];
-
-/**
- * Lee un archivo de texto de forma segura. Devuelve null si el archivo no existe o no puede leerse.
- */
-export function readFile(filePath: string): string | null;
-
-/** Escribe un archivo de texto, creando los directorios padre si es necesario */
-export function writeFile(filePath: string, content: string): void;
-
-/** Agrega contenido a un archivo de texto, creando los directorios padre si es necesario */
-export function appendFile(filePath: string, content: string): void;
-
-export interface ReplaceInFileOptions {
-  /**
-   * Si es true y search es una cadena, reemplaza TODAS las ocurrencias (usa String.replaceAll).
-   * Se ignora para patrones RegExp — usa la bandera `g` en su lugar.
-   */
-  all?: boolean;
-}
-
-/**
- * Reemplaza texto en un archivo (alternativa multiplataforma a sed).
- * @returns true si el archivo se encontró y actualizó, false si no se encontró
- */
-export function replaceInFile(filePath: string, search: string | RegExp, replace: string, options?: ReplaceInFileOptions): boolean;
-
-/**
- * Cuenta las ocurrencias de un patrón en un archivo.
- * La bandera global se fuerza automáticamente para un conteo correcto.
- */
-export function countInFile(filePath: string, pattern: string | RegExp): number;
-
-export interface GrepMatch {
-  /** Número de línea (base 1) */
-  lineNumber: number;
-  /** Contenido completo de la línea coincidente */
-  content: string;
-}
-
-/** Busca un patrón en un archivo y devuelve las líneas coincidentes con su número de línea */
-export function grepFile(filePath: string, pattern: string | RegExp): GrepMatch[];
-
-// --- E/S de hooks ---
-
-export interface ReadStdinJsonOptions {
-  /**
-   * Timeout en milisegundos. Evita que los hooks queden colgados
-   * indefinidamente si stdin nunca se cierra. Por defecto: 5000
-   */
-  timeoutMs?: number;
-  /**
-   * Tamaño máximo de datos de stdin en bytes. Evita crecimiento de memoria sin límite.
-   * Por defecto: 1048576 (1MB)
-   */
-  maxSize?: number;
-}
-
-/**
- * Lee JSON desde stdin (para la entrada de los hooks).
- * Devuelve un objeto vacío si stdin está vacío, expira el timeout o contiene JSON inválido.
- * Nunca rechaza — seguro de usar sin try-catch en los hooks.
- */
-export function readStdinJson(options?: ReadStdinJsonOptions): Promise<Record<string, unknown>>;
-
-/** Escribe un mensaje en stderr (visible para el usuario en la terminal de Theus) */
-export function log(message: string): void;
-
-/** Escribe datos en stdout (se devuelven al contexto del agente) */
-export function output(data: string | Record<string, unknown>): void;
-
-// --- Sistema ---
-
-/**
- * Comprueba si un comando existe en el PATH.
- * Solo permite caracteres alfanuméricos, guion, guion bajo y punto.
- * ADVERTENCIA: lanza un proceso hijo (where.exe en Windows, which en Unix).
- */
-export function commandExists(cmd: string): boolean;
-
-export interface CommandResult {
-  success: boolean;
-  /** stdout recortado en caso de éxito; stderr o mensaje de error en caso de fallo */
-  output: string;
-}
-
-/**
- * Ejecuta un comando de shell y devuelve su salida.
- * SEGURIDAD: úsalo solo con comandos confiables y fijos en el código.
- * Nunca pases entrada controlada por el usuario directamente.
- */
-export function runCommand(cmd: string, options?: ExecSyncOptions): CommandResult;
-
-/** Comprueba si el directorio actual está dentro de un repositorio git */
-export function isGitRepo(): boolean;
-
-/**
- * Obtiene los archivos modificados según git (staged + sin stage), opcionalmente
- * filtrados por patrones regex. Los patrones inválidos se omiten silenciosamente.
- */
-export function getGitModifiedFiles(patterns?: string[]): string[];