@axplusb/kepler 2.0.6 → 2.2.0

package/src/core/policy-resolver.mjs

@@ -0,0 +1,156 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+export const DEFAULT_POLICY = Object.freeze({
+  version: 1,
+  context: {
+    loadEveryTurn: ['KEPLER.md', 'project.md', 'style.md', 'goal.md', 'plan.md', 'tasks/*.md'],
+    showReloadNotice: true,
+    injectCommandOptions: true,
+    injectActionableTips: true,
+    tipTtlTurns: 2,
+  },
+  planning: {
+    owner: 'auto',
+    allowedOwners: ['main_agent', 'planner_subagent', 'auto', 'manual'],
+    delegateWhen: {
+      taskCountGte: 4,
+      estimatedFilesGte: 6,
+      touchesMultiplePackages: true,
+    },
+    onUserEditedPlan: 'prefer_user_plan',
+  },
+  tasks: {
+    storage: 'project_markdown',
+    syncTodoWrite: true,
+    resumePrompt: true,
+  },
+  commands: {
+    enabled: ['map', 'probe', 'footprint', 'heal', 'align', 'distill', 'brief', 'rewind'],
+    defaultMode: 'interactive',
+    dryRunDefault: false,
+    suggestions: true,
+    suggestOnlyWhenActionable: true,
+    timeouts: {
+      defaultSeconds: 300,
+      healSeconds: 600,
+      probeSeconds: 180,
+      briefSeconds: 60,
+    },
+    aliases: {
+      fix: 'heal',
+      repair: 'heal',
+      search: 'probe',
+      summarize: 'brief',
+    },
+  },
+  hitl: {
+    defaultScope: 'once',
+    allowSessionTrust: true,
+    allowProjectTrust: false,
+    reaskAfterMinutes: 30,
+    reaskOnCommandShapeChange: true,
+    reaskOnRiskIncrease: true,
+    reaskOnPathBoundaryChange: true,
+    alwaysAskForDangerous: true,
+  },
+  hooks: {
+    timeoutSeconds: 5,
+  },
+  ui: {
+    recentActions: true,
+    verbosity: 'normal',
+  },
+});
+
+export function deepClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+export function deepMerge(target, source) {
+  if (!source || typeof source !== 'object') return deepClone(target);
+  const result = Array.isArray(target) ? [...target] : { ...(target || {}) };
+  for (const [key, value] of Object.entries(source)) {
+    if (
+      value &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      result[key] &&
+      typeof result[key] === 'object' &&
+      !Array.isArray(result[key])
+    ) {
+      result[key] = deepMerge(result[key], value);
+    } else {
+      result[key] = deepClone(value);
+    }
+  }
+  return result;
+}
+
+function readJson(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch (err) {
+    return { __error: err.message };
+  }
+}
+
+function projectConfigPath(cwd) {
+  return path.join(cwd, '.kepler', 'config.json');
+}
+
+function globalPolicyPath() {
+  return path.join(os.homedir(), '.kepler', 'policy.json');
+}
+
+function flatten(obj, prefix = '', out = []) {
+  for (const [key, value] of Object.entries(obj || {})) {
+    const dotted = prefix ? `${prefix}.${key}` : key;
+    if (value && typeof value === 'object' && !Array.isArray(value)) flatten(value, dotted, out);
+    else out.push([dotted, value]);
+  }
+  return out;
+}
+
+export function loadEffectivePolicy({ cwd = process.cwd(), cli = {}, session = {} } = {}) {
+  const layers = [
+    { name: 'default', path: null, data: deepClone(DEFAULT_POLICY) },
+  ];
+
+  const global = readJson(globalPolicyPath());
+  if (global && !global.__error) layers.push({ name: 'global', path: globalPolicyPath(), data: global });
+  else if (global?.__error) layers.push({ name: 'global', path: globalPolicyPath(), error: global.__error, data: {} });
+
+  const project = readJson(projectConfigPath(cwd));
+  if (project && !project.__error) layers.push({ name: 'project', path: projectConfigPath(cwd), data: project });
+  else if (project?.__error) layers.push({ name: 'project', path: projectConfigPath(cwd), error: project.__error, data: {} });
+
+  if (session && Object.keys(session).length > 0) layers.push({ name: 'session', path: null, data: session });
+  if (cli && Object.keys(cli).length > 0) layers.push({ name: 'cli', path: null, data: cli });
+
+  let policy = {};
+  const sources = {};
+  for (const layer of layers) {
+    policy = deepMerge(policy, layer.data || {});
+    for (const [key, value] of flatten(layer.data || {})) {
+      sources[key] = { source: layer.name, path: layer.path, value };
+    }
+  }
+
+  return { policy, sources, layers };
+}
+
+export function formatPolicySourceRows(effective) {
+  const rows = [];
+  for (const [key, meta] of Object.entries(effective?.sources || {}).sort()) {
+    rows.push({
+      key,
+      source: meta.source,
+      path: meta.path || '',
+      value: meta.value,
+    });
+  }
+  return rows;
+}

package/src/core/project-context-loader.mjs

@@ -0,0 +1,139 @@
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { loadKeplerMemory } from '../config/memory-loader.mjs';
+
+function sha(content) {
+  return crypto.createHash('sha256').update(content || '').digest('hex').slice(0, 12);
+}
+
+function readFile(filePath, label, maxChars = 12000) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return {
+      label,
+      path: filePath,
+      hash: sha(content),
+      bytes: Buffer.byteLength(content),
+      content: content.length > maxChars
+        ? content.slice(0, maxChars) + '\n\n[...truncated...]'
+        : content,
+      truncated: content.length > maxChars,
+    };
+  } catch (err) {
+    return { label, path: filePath, error: err.message, content: '' };
+  }
+}
+
+function readTasks(keplerDir) {
+  const tasksDir = path.join(keplerDir, 'tasks');
+  const files = [];
+  try {
+    if (!fs.existsSync(tasksDir)) return files;
+    for (const name of fs.readdirSync(tasksDir).sort()) {
+      if (!name.endsWith('.md')) continue;
+      const file = readFile(path.join(tasksDir, name), `tasks/${name}`, 6000);
+      if (file) files.push(file);
+    }
+  } catch { /* best effort */ }
+  return files;
+}
+
+function scanSkills(dir, scope) {
+  const skillsDir = path.join(dir, 'skills');
+  const out = [];
+  try {
+    if (!fs.existsSync(skillsDir)) return out;
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+      let filePath = null;
+      let name = entry.name;
+      if (entry.isDirectory()) filePath = path.join(skillsDir, entry.name, 'SKILL.md');
+      else if (entry.isFile() && entry.name.endsWith('.md')) {
+        filePath = path.join(skillsDir, entry.name);
+        name = entry.name.replace(/\.md$/, '');
+      }
+      if (!filePath || !fs.existsSync(filePath)) continue;
+      const raw = fs.readFileSync(filePath, 'utf-8');
+      const desc = raw.match(/^description:\s*(.+)$/mi)?.[1]?.trim()
+        || raw.match(/^#\s+.+\n+([^\n]+)/)?.[1]?.trim()
+        || '';
+      out.push({ name, description: desc, scope, source_id: `${scope}:${name}`, path: filePath });
+    }
+  } catch { /* best effort */ }
+  return out;
+}
+
+export function loadProjectContext({ cwd = process.cwd(), previous = null } = {}) {
+  const keplerDir = path.join(cwd, '.kepler');
+  const files = [];
+  for (const file of loadKeplerMemory({ cwd })) {
+    const label = file.path.endsWith(path.join('.kepler', 'KEPLER.md'))
+      ? 'KEPLER.md'
+      : path.basename(file.path);
+    files.push({
+      label,
+      source: file.source,
+      path: file.path,
+      hash: sha(file.content),
+      bytes: Buffer.byteLength(file.content),
+      content: file.content,
+    });
+  }
+
+  for (const name of ['config.json', 'project.md', 'style.md', 'goal.md', 'plan.md', 'hitl.md']) {
+    const file = readFile(path.join(keplerDir, name), name, name.endsWith('.json') ? 4000 : 12000);
+    if (file) files.push(file);
+  }
+  files.push(...readTasks(keplerDir));
+
+  const previousHashes = new Map((previous?.files || []).map(f => [f.path, f.hash]));
+  const changed = files.filter(f => f.hash && previousHashes.get(f.path) && previousHashes.get(f.path) !== f.hash);
+  const loaded = files.filter(f => !f.error).map(f => ({
+    label: f.label,
+    path: f.path,
+    hash: f.hash,
+    bytes: f.bytes,
+    source: f.source || 'project',
+    included: true,
+    changed: changed.some(c => c.path === f.path),
+  }));
+
+  const skills = [
+    ...scanSkills(path.join(os.homedir(), '.kepler'), 'global'),
+    ...scanSkills(keplerDir, 'project'),
+  ];
+  const byName = new Map();
+  for (const skill of skills) byName.set(skill.name, skill);
+
+  return {
+    root: cwd,
+    kepler_dir: keplerDir,
+    files,
+    loaded,
+    changed,
+    available_skills: [...byName.values()],
+    task_state: files
+      .filter(f => f.label.startsWith('tasks/'))
+      .map(f => ({ name: f.label.replace('tasks/', ''), hash: f.hash, content: f.content })),
+    loaded_at: new Date().toISOString(),
+  };
+}
+
+export function contextToPromptBlock(context) {
+  const parts = [];
+  if (context?.root) {
+    parts.push([
+      '--- task workflow ---',
+      'Keep .kepler/tasks/active.md current for the work in progress.',
+      'Use .kepler/tasks/backlog.md for deferred work, .kepler/tasks/blocked.md for items waiting on input, and .kepler/tasks/done.md for completed work.',
+      'When the task state changes materially, update the appropriate task markdown file before the turn finishes.',
+    ].join('\n'));
+  }
+  for (const file of context?.files || []) {
+    if (!file.content || file.label === 'config.json') continue;
+    parts.push(`--- ${file.label} (${file.hash}) ---\n${file.content}`);
+  }
+  return parts.join('\n\n');
+}

package/src/core/rate-limit-display.mjs

@@ -0,0 +1,97 @@
+/**
+ * User-facing helpers for PRD-065 rolling message windows.
+ */
+
+export function normalizeRateLimit(rateLimit) {
+    if (!rateLimit || typeof rateLimit !== 'object') return null;
+
+    const used = numberOrNull(rateLimit.msgs_used_in_window);
+    const limit = numberOrNull(rateLimit.msgs_per_window);
+    const configured = numberOrNull(rateLimit.configured_msgs_per_window);
+    const retryAfter = numberOrNull(rateLimit.retry_after ?? rateLimit.retry_after_seconds);
+
+    return {
+        ...rateLimit,
+        msgs_used_in_window: used,
+        msgs_per_window: limit,
+        configured_msgs_per_window: configured,
+        retry_after: retryAfter,
+        unlimited: Boolean(rateLimit.unlimited),
+        byok: Boolean(rateLimit.byok),
+    };
+}
+
+export function messagesRemaining(rateLimit) {
+    const rl = normalizeRateLimit(rateLimit);
+    if (!rl) return null;
+    if (rl.unlimited || rl.msgs_per_window === -1) return Infinity;
+    if (typeof rl.msgs_used_in_window !== 'number' || typeof rl.msgs_per_window !== 'number') return null;
+    return Math.max(0, rl.msgs_per_window - rl.msgs_used_in_window);
+}
+
+export function formatRetryAfter(seconds) {
+    const secs = Math.max(0, Math.ceil(Number(seconds) || 0));
+    if (secs <= 0) return 'soon';
+    const hours = Math.floor(secs / 3600);
+    const minutes = Math.ceil((secs % 3600) / 60);
+    if (hours > 0 && minutes > 0) return `${hours}h ${minutes}m`;
+    if (hours > 0) return `${hours}h`;
+    if (minutes > 0) return `${minutes}m`;
+    return `${secs}s`;
+}
+
+export function resetLabel(rateLimit, now = Date.now()) {
+    const rl = normalizeRateLimit(rateLimit);
+    if (!rl?.window_reset_at) return null;
+    const resetMs = Date.parse(rl.window_reset_at);
+    if (!Number.isFinite(resetMs)) return null;
+    return formatRetryAfter(Math.max(0, (resetMs - now) / 1000));
+}
+
+export function formatMessageWindow(rateLimit, { includeReset = true } = {}) {
+    const rl = normalizeRateLimit(rateLimit);
+    if (!rl) return null;
+
+    const tier = rl.tier ? String(rl.tier).toUpperCase() : null;
+    if (rl.byok || rl.unlimited || rl.msgs_per_window === -1) {
+        return [tier, 'unlimited messages'].filter(Boolean).join(' · ');
+    }
+
+    if (typeof rl.msgs_used_in_window !== 'number' || typeof rl.msgs_per_window !== 'number') {
+        return tier || null;
+    }
+
+    const remaining = Math.max(0, rl.msgs_per_window - rl.msgs_used_in_window);
+    const parts = [
+        tier,
+        `${remaining} / ${rl.msgs_per_window} messages this window`,
+    ].filter(Boolean);
+
+    const reset = includeReset ? resetLabel(rl) : null;
+    if (reset) parts.push(`resets in ${reset}`);
+    return parts.join(' · ');
+}
+
+export function lowWindowStatus(rateLimit) {
+    const rl = normalizeRateLimit(rateLimit);
+    if (!rl || rl.byok || rl.unlimited || rl.msgs_per_window === -1) return 'ok';
+    const remaining = messagesRemaining(rl);
+    if (typeof remaining !== 'number' || typeof rl.msgs_per_window !== 'number') return 'ok';
+    if (remaining <= 0) return 'exhausted';
+    if (remaining <= Math.max(5, Math.floor(rl.msgs_per_window * 0.2))) return 'low';
+    return 'ok';
+}
+
+export function rateLimitErrorMessage(payload, fallback = 'Message limit reached.') {
+    const detail = payload?.detail && typeof payload.detail === 'object' ? payload.detail : payload;
+    const retryAfter = detail?.retry_after ?? detail?.rate_limit?.retry_after ?? detail?.rate_limit?.retry_after_seconds;
+    if (detail?.message) return detail.message;
+    if (retryAfter != null) return `Message limit reached — try again in ${formatRetryAfter(retryAfter)}.`;
+    return fallback;
+}
+
+function numberOrNull(value) {
+    if (value == null) return null;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+}

package/src/core/resume-mode.mjs

@@ -0,0 +1,154 @@
+/**
+ * Resume Mode — decide how much of a transcript to send to the agent (PRD-068 §5.14.3).
+ *
+ * Rule of thumb: if the projected context (transcript + system prompt overhead)
+ * fits comfortably in the current model's window, resume with `full` silently.
+ * Only ask the user when we're above the highWatermark.
+ *
+ * Config lives in .kepler/settings.json:
+ *   {
+ *     "resume": {
+ *       "highWatermark": 0.50,   // prompt above this (default 50%)
+ *       "hardCap":       0.85    // refuse full above this  (default 85%)
+ *     }
+ *   }
+ */
+
+// System overhead — tools, memory, .kepler/ context, kepler.md, skills index.
+// Rough constant; individual runs vary. Tuned toward "assume ~4k of overhead".
+const DEFAULT_SYSTEM_OVERHEAD_TOKENS = 4000;
+
+// Model context windows we know about. Fallback used when unknown.
+// Keep this table small — it's a hint, not a source of truth.
+const MODEL_CONTEXT_WINDOWS = {
+  'anthropic/claude-sonnet-4':          200000,
+  'anthropic/claude-4-sonnet-20250522': 200000,
+  'anthropic/claude-opus-4':            200000,
+  'deepseek/deepseek-v4-flash':         128000,
+  'deepseek/deepseek-v4-pro':           128000,
+  'deepseek/deepseek-chat-v3-0324':     128000,
+  'openai/gpt-5':                       400000,
+  'openai/gpt-5-mini':                  400000,
+  'google/gemini-2.5-pro':              1000000,
+  'xiaomi/mimo-v2.5':                   128000,
+};
+const DEFAULT_CONTEXT_WINDOW = 128000;
+
+export function modelContextWindow(model) {
+  if (!model) return DEFAULT_CONTEXT_WINDOW;
+  return MODEL_CONTEXT_WINDOWS[model] || DEFAULT_CONTEXT_WINDOW;
+}
+
+/**
+ * Decide the resume mode for a session based on projected context usage.
+ *
+ * @param {object} args
+ * @param {number} args.transcriptTokens  — projected transcript size when serialized
+ * @param {string} [args.model]           — current agent model id
+ * @param {object} [args.settings]        — .kepler/settings.json contents (optional)
+ * @param {number} [args.systemOverhead]  — override system overhead (defaults to 4k)
+ * @returns {{
+ *   mode:          'full' | 'ask' | 'no-full-allowed',
+ *   defaultChoice: 'full' | 'tail-20' | 'summary',
+ *   projected:     number,   // total projected tokens
+ *   windowSize:    number,   // model window
+ *   usageRatio:    number,   // projected / windowSize
+ *   highWatermark: number,
+ *   hardCap:       number,
+ * }}
+ *
+ * `mode = 'full'`             — resume immediately in full mode; do not prompt
+ * `mode = 'ask'`              — show the tri-choice overlay
+ * `mode = 'no-full-allowed'`  — above hardCap; user must pick a tail mode or summary
+ */
+export function decideResumeMode({
+  transcriptTokens,
+  model,
+  settings,
+  systemOverhead = DEFAULT_SYSTEM_OVERHEAD_TOKENS,
+} = {}) {
+  const cfg = settings?.resume || {};
+  const highWatermark = clampRatio(cfg.highWatermark, 0.50);
+  const hardCap = clampRatio(cfg.hardCap, 0.85);
+
+  const windowSize = modelContextWindow(model);
+  const projected = Math.max(0, Number(transcriptTokens) || 0) + systemOverhead;
+  const usageRatio = windowSize > 0 ? projected / windowSize : 0;
+
+  let mode;
+  let defaultChoice;
+  if (usageRatio > hardCap) {
+    mode = 'no-full-allowed';
+    // Above hardCap — last 20 turns is usually the least-lossy fit; user picks.
+    defaultChoice = 'tail-20';
+  } else if (usageRatio > highWatermark) {
+    mode = 'ask';
+    defaultChoice = 'full';
+  } else {
+    mode = 'full';
+    defaultChoice = 'full';
+  }
+
+  return {
+    mode,
+    defaultChoice,
+    projected,
+    windowSize,
+    usageRatio,
+    highWatermark,
+    hardCap,
+  };
+}
+
+/**
+ * Estimate the context tokens for a candidate mode. Used by the tri-choice
+ * overlay to render "62k / 14k / 2k" per option before the user commits.
+ *
+ * @param {'full' | 'summary' | 'tail-10' | 'tail-20' | 'recap+tail'} choice
+ * @param {number} fullTokens — projected transcript size in full mode
+ * @param {object} [opts]
+ * @returns {number} projected tokens for the chosen mode
+ */
+export function projectedTokensForChoice(choice, fullTokens, opts = {}) {
+  const {
+    tailTurns = null,
+    // Rough per-turn estimate. Summary block is ~1-2k.
+    tailBaseTokens = 2000,
+    perTailTurnTokens = 500,
+    summaryBaseTokens = 2000,
+  } = opts;
+
+  switch (choice) {
+    case 'full':
+      return Math.max(0, Number(fullTokens) || 0);
+    case 'tail-10':
+      return tailBaseTokens + (10 * perTailTurnTokens);
+    case 'tail-20':
+      return tailBaseTokens + (20 * perTailTurnTokens);
+    case 'recap+tail':
+      return tailBaseTokens + ((Number(tailTurns) || 8) * perTailTurnTokens);
+    case 'summary':
+      return summaryBaseTokens;
+    default:
+      return Math.max(0, Number(fullTokens) || 0);
+  }
+}
+
+function clampRatio(value, fallback) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  if (n <= 0) return fallback;
+  if (n > 1) return fallback;
+  return n;
+}
+
+/**
+ * Format tokens with a k/M suffix — "8k", "62k", "1.2M".
+ * Used by the picker + overlay so numbers fit in narrow columns.
+ */
+export function formatTokens(n) {
+  const v = Math.round(Number(n) || 0);
+  if (v < 1000) return `${v}`;
+  if (v < 1_000_000) return `${Math.round(v / 1000)}k`;
+  return `${(v / 1_000_000).toFixed(1)}M`;
+}