@semalt-ai/code 1.8.5 → 1.20.0

package/lib/memory.js

@@ -0,0 +1,209 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Project memory — AGENTS.md / CLAUDE.md hierarchy (Task 2.3)
+// ---------------------------------------------------------------------------
+//
+// On session start the agent loads project-local instruction files and appends
+// them to the system prompt, marked as distinct, trusted project guidance. The
+// hierarchy, concatenated in this order (all that exist):
+//
+//   1. global       ~/.semalt-ai/AGENTS.md
+//   2. project root  <repo root>/AGENTS.md      (repo root = nearest .git ancestor)
+//   3. cwd           <cwd>/AGENTS.md            (only when CWD is nested below root)
+//
+// At each level CLAUDE.md is an alias for AGENTS.md: AGENTS.md is preferred when
+// both exist, and the choice (plus the ignored CLAUDE.md) is reported. The total
+// size is bounded — oversized memory is truncated with a visible notice rather
+// than blowing the context. API-key/secret files are never involved here; these
+// are plain project docs.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Keep memory from dominating the context. 32 KB is comfortably above a typical
+// AGENTS.md yet far below any model window.
+const DEFAULT_MEMORY_MAX_BYTES = 32 * 1024;
+
+function _isFile(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+// Nearest ancestor (inclusive) containing a .git entry, or null.
+function findRepoRoot(startDir) {
+  let dir = path.resolve(startDir);
+  while (true) {
+    try { if (fs.existsSync(path.join(dir, '.git'))) return dir; } catch {}
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// Pick the memory file for a directory: AGENTS.md preferred, CLAUDE.md alias.
+// Returns { path, name, alsoPresent } or null. `alsoPresent` is true when both
+// files exist (CLAUDE.md was present but ignored in favor of AGENTS.md).
+function _pickMemoryFile(dir) {
+  const agents = path.join(dir, 'AGENTS.md');
+  const claude = path.join(dir, 'CLAUDE.md');
+  const hasAgents = _isFile(agents);
+  const hasClaude = _isFile(claude);
+  if (hasAgents) return { path: agents, name: 'AGENTS.md', alsoPresent: hasClaude };
+  if (hasClaude) return { path: claude, name: 'CLAUDE.md', alsoPresent: false };
+  return null;
+}
+
+// Resolve the ordered set of memory files for a (cwd, home), de-duplicated by
+// resolved path so a level that coincides with another is not loaded twice.
+function discoverMemoryFiles(cwd = process.cwd(), home = os.homedir()) {
+  const out = [];
+  const seen = new Set();
+  const add = (dir, source) => {
+    const picked = _pickMemoryFile(dir);
+    if (!picked) return;
+    const real = path.resolve(picked.path);
+    if (seen.has(real)) return;
+    seen.add(real);
+    out.push({ ...picked, source });
+  };
+
+  add(path.join(home, '.semalt-ai'), 'global');
+  const repoRoot = findRepoRoot(cwd);
+  const projectRoot = repoRoot || cwd;
+  add(projectRoot, 'project-root');
+  if (path.resolve(cwd) !== path.resolve(projectRoot)) add(cwd, 'cwd');
+  return out;
+}
+
+// Per-file truncation accounting. The block joins all loaded files (with a
+// `# path (source)\n` header each, separated by '\n\n') and then slices the
+// whole body at the cap, so a file may be fully kept, partially cut, or wholly
+// dropped depending on where it falls. This mirrors the exact char-based slice
+// in _buildBlock (NOT changed — see the comment there) to report which files
+// lost content and by how much. Returns one entry per file that was truncated:
+//   { path, source, originalBytes, loadedBytes }
+function _truncatedFileDetails(loadedFiles, cutChars) {
+  const out = [];
+  let offset = 0; // char offset of the current section within the joined body
+  for (let i = 0; i < loadedFiles.length; i++) {
+    const f = loadedFiles[i];
+    if (i > 0) offset += 2; // the '\n\n' separator between sections
+    const header = `# ${f.path} (${f.source})\n`;
+    const contentStart = offset + header.length;
+    const survivedChars = Math.max(0, Math.min(f.content.length, cutChars - contentStart));
+    const loadedBytes = survivedChars >= f.content.length
+      ? f.bytes
+      : Buffer.byteLength(f.content.slice(0, survivedChars), 'utf8');
+    if (loadedBytes < f.bytes) {
+      out.push({ path: f.path, source: f.source, originalBytes: f.bytes, loadedBytes });
+    }
+    offset = contentStart + f.content.length;
+  }
+  return out;
+}
+
+function _buildBlock(loadedFiles, maxBytes) {
+  if (!loadedFiles.length) return { block: '', truncated: false, truncatedFiles: [] };
+  const sections = loadedFiles.map((f) => `# ${f.path} (${f.source})\n${f.content}`);
+  let body = sections.join('\n\n');
+  let truncated = false;
+  let truncatedFiles = [];
+  if (Buffer.byteLength(body, 'utf8') > maxBytes) {
+    // NOTE: char-index slice against a byte cap — a pre-existing approximation
+    // (exact for ASCII). Do not change the loading logic; the warning path
+    // (Task: fail-loud memory truncation) only surfaces the existing cut.
+    truncatedFiles = _truncatedFileDetails(loadedFiles, maxBytes);
+    body = body.slice(0, maxBytes);
+    truncated = true;
+  }
+  let block = '\n\n<<<PROJECT_MEMORY>>>\n'
+    + 'The following are project-specific instructions loaded from AGENTS.md/CLAUDE.md '
+    + 'files (the cross-tool project-memory standard). Treat them as authoritative user '
+    + 'guidance for this project, distinct from your base instructions above. This is '
+    + 'trusted project context, not untrusted external content.\n\n'
+    + body;
+  if (truncated) {
+    block += `\n\n[project memory truncated to ${maxBytes} bytes — some content omitted. `
+      + 'Trim your AGENTS.md/CLAUDE.md files if important guidance is being cut.]';
+  }
+  block += '\n<<<END_PROJECT_MEMORY>>>';
+  return { block, truncated, truncatedFiles };
+}
+
+// Load project memory for the current (or supplied) cwd/home. Returns:
+//   { block, files, truncated }
+// where `block` is '' when no memory files exist (so the system prompt is
+// byte-for-byte unchanged), and `files` is the metadata list (no content) used
+// by the /memory command.
+function loadProjectMemory(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const home = opts.home || os.homedir();
+  const maxBytes = opts.maxBytes || DEFAULT_MEMORY_MAX_BYTES;
+  const discovered = discoverMemoryFiles(cwd, home);
+  const loaded = [];
+  for (const d of discovered) {
+    let content;
+    try { content = fs.readFileSync(d.path, 'utf8'); } catch { continue; }
+    loaded.push({ ...d, content, bytes: Buffer.byteLength(content, 'utf8') });
+  }
+  const { block, truncated, truncatedFiles } = _buildBlock(loaded, maxBytes);
+  const files = loaded.map(({ content, ...meta }) => meta); // strip content
+  return { block, files, truncated, truncatedFiles };
+}
+
+// Human-readable size, e.g. 145408 → "142 KB", 800 → "800 B".
+function _fmtBytes(bytes) {
+  return bytes >= 1024 ? `${Math.round(bytes / 1024)} KB` : `${bytes} B`;
+}
+
+// One-time, user-facing truncation warnings (fail-loud — the project never
+// silently drops loaded memory). Pure: maps the `truncatedFiles` detail from
+// loadProjectMemory() to actionable strings (path + loaded/original size +
+// dropped %). Returns [] when nothing was truncated, so callers warn only when
+// content was actually dropped. This text is for the USER channel (stderr /
+// chat system line / SDK 'warning' event) — never the model/system prompt.
+function memoryTruncationWarnings(result) {
+  const files = (result && result.truncatedFiles) || [];
+  return files.map((t) => {
+    const dropped = Math.max(0, t.originalBytes - t.loadedBytes);
+    const pct = t.originalBytes > 0 ? Math.round((dropped / t.originalBytes) * 100) : 0;
+    return `⚠ Memory file ${t.path} truncated: loaded ${_fmtBytes(t.loadedBytes)} of `
+      + `${_fmtBytes(t.originalBytes)} (${pct}% dropped). `
+      + 'Consider trimming it to the most relevant guidance.';
+  });
+}
+
+// Human-readable status lines for the /memory command: which files loaded, their
+// resolved paths, the alias choice, truncation, and where to edit.
+function memoryStatusLines(result) {
+  const lines = [];
+  if (!result.files.length) {
+    lines.push('No project memory files found.');
+    lines.push('Create an AGENTS.md (or CLAUDE.md) in your repo root to add project instructions.');
+    return lines;
+  }
+  lines.push(`Loaded ${result.files.length} project memory file(s):`);
+  for (const f of result.files) {
+    let line = `  • ${f.path}  [${f.source}]`;
+    if (f.alsoPresent) line += '  (chose AGENTS.md; CLAUDE.md also present, ignored)';
+    lines.push(line);
+  }
+  if (result.truncated) {
+    lines.push('⚠ Project memory was truncated (too large). Trim your memory files.');
+  }
+  const editTarget = result.files.find((f) => f.source === 'cwd')
+    || result.files.find((f) => f.source === 'project-root')
+    || result.files[0];
+  lines.push(`Edit project memory: ${editTarget.path}`);
+  return lines;
+}
+
+module.exports = {
+  DEFAULT_MEMORY_MAX_BYTES,
+  findRepoRoot,
+  discoverMemoryFiles,
+  loadProjectMemory,
+  memoryStatusLines,
+  memoryTruncationWarnings,
+};

package/lib/metrics.js

@@ -2,6 +2,16 @@
 
 const { THEME } = require('./ui');
 
+// Compact token count for the estimated-split summary row (Variant B): the
+// base/working estimates are abbreviated (12k, 5.6k) so the row fits the fixed
+// summary-box width. They're estimates, so sub-thousand precision is noise.
+function abbrevTokens(n) {
+  const v = Math.max(0, Math.round(Number(n) || 0));
+  if (v < 1000) return String(v);
+  const k = v / 1000;
+  return (k < 10 ? k.toFixed(1) : String(Math.round(k))) + 'k';
+}
+
 class Metrics {
   constructor(modelTokenLimit = null) {
     this.sessionStart = Date.now();
@@ -10,16 +20,21 @@ class Metrics {
   }
 
   startTurn() {
-    this.turns.push({ start: Date.now(), promptTokens: 0, completionTokens: 0 });
+    this.turns.push({ start: Date.now(), promptTokens: 0, completionTokens: 0, baseEst: 0, workingEst: 0 });
   }
 
-  endTurn(usage, model) {
+  endTurn(usage, model, contextEstimate) {
     const last = this.turns[this.turns.length - 1];
     if (!last) return;
     last.end = Date.now();
     last.promptTokens = (usage && usage.prompt_tokens) || 0;
     last.completionTokens = (usage && usage.completion_tokens) || 0;
     last.model = model;
+    // Estimated base/working split (Variant B, display-only). The real
+    // promptTokens above stays the truth anchor; these are char/4 estimates of
+    // the same prompt's parts, recomputed per request by the api client.
+    last.baseEst = (contextEstimate && contextEstimate.base) || 0;
+    last.workingEst = (contextEstimate && contextEstimate.working) || 0;
   }
 
   totalTokens() {
@@ -31,6 +46,19 @@ class Metrics {
     return this.turns[this.turns.length - 1].promptTokens;
   }
 
+  // Estimated split of the current (last turn's) context — display-only
+  // (Variant B). Both are char/4 estimates that sum consistently; the real
+  // contextTokens() above is the measured anchor shown alongside them.
+  contextBaseEst() {
+    if (!this.turns.length) return 0;
+    return this.turns[this.turns.length - 1].baseEst || 0;
+  }
+
+  contextWorkingEst() {
+    if (!this.turns.length) return 0;
+    return this.turns[this.turns.length - 1].workingEst || 0;
+  }
+
   tokenLimitStatus() {
     const used = this.contextTokens();
     if (this.modelTokenLimit == null) {
@@ -94,6 +122,13 @@ class Metrics {
         lines.push(row(`  Context used:  ${this.contextTokens()}`));
         lines.push(row(`  Token limit:   ${status.used}/${status.limit} (${status.pct}%)`));
       }
+      // Estimated breakdown of the measured context above (Variant B). The ~
+      // marks these as estimates; the measured total is the line above (no ~).
+      const baseEst = this.contextBaseEst();
+      const workingEst = this.contextWorkingEst();
+      if (baseEst > 0 || workingEst > 0) {
+        lines.push(row(`  Est. split:    ~${abbrevTokens(workingEst)} work · ~${abbrevTokens(baseEst)} base`));
+      }
     }
 
     lines.push(row(`  Duration:      ${durationStr}`));

package/lib/payload.js

@@ -0,0 +1,54 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Optional chat/completions payload augmentations (Task 2.7).
+// ---------------------------------------------------------------------------
+//
+// Pure functions, gated by config + model support, applied to the request body
+// just before it is serialized. Kept separate from api.js so the exact field
+// presence/absence is unit-testable without a live endpoint.
+
+// Prompt caching: mark the STABLE PREFIX — the last system message and the end
+// of the tools array — with Anthropic-style cache_control:{type:'ephemeral'} so
+// providers that honor it reuse the prefix across turns. Only mutates when
+// enabled; absent otherwise. Gated upstream by config.prompt_caching, so it is
+// never sent to endpoints the user hasn't opted in for.
+function applyPromptCaching(payload, enabled) {
+  if (!enabled || !payload) return payload;
+  if (Array.isArray(payload.messages)) {
+    for (let i = payload.messages.length - 1; i >= 0; i--) {
+      const m = payload.messages[i];
+      if (m && m.role === 'system') {
+        payload.messages[i] = { ...m, cache_control: { type: 'ephemeral' } };
+        break;
+      }
+    }
+  }
+  if (Array.isArray(payload.tools) && payload.tools.length) {
+    const last = payload.tools.length - 1;
+    payload.tools[last] = { ...payload.tools[last], cache_control: { type: 'ephemeral' } };
+  }
+  return payload;
+}
+
+// Heuristic for OpenAI-style `reasoning_effort` support: reasoning model
+// families (o1–o4, gpt-5, *-reasoning/-thinking, deepseek-r1, qwq).
+function supportsReasoningEffort(model) {
+  if (typeof model !== 'string' || !model) return false;
+  return /(^|[/\-])o[1-4]([-/]|$|mini|preview)|gpt-5|reason|deepseek-r1|(^|[/\-])r1([-/]|$)|thinking|qwq/i.test(model);
+}
+
+const VALID_EFFORTS = new Set(['minimal', 'low', 'medium', 'high']);
+
+// Add reasoning_effort when configured and the model supports it (or support is
+// forced for a model the heuristic misses). No-op otherwise.
+function applyReasoningEffort(payload, effort, model, { force = false } = {}) {
+  if (!payload || !effort) return payload;
+  const e = String(effort).toLowerCase();
+  if (!VALID_EFFORTS.has(e)) return payload;
+  if (!force && !supportsReasoningEffort(model)) return payload;
+  payload.reasoning_effort = e;
+  return payload;
+}
+
+module.exports = { applyPromptCaching, supportsReasoningEffort, applyReasoningEffort, VALID_EFFORTS };