theus-cli-darwin-x64 0.2.84

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

@@ -0,0 +1,232 @@
+/**
+ * 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

@@ -0,0 +1,205 @@
+/**
+ * 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[];