minimal-agent 0.10.0 → 0.12.0

package/src/context/contextBundle.js

@@ -0,0 +1,119 @@
+import { countTextTokens } from './tokenCounter.js';
+export const DEFAULT_TRANSIENT_BUDGET_TOKENS = 3_000;
+export function contextFragment(input) {
+    const content = input.content.trim();
+    return {
+        ...input,
+        content,
+        estimatedTokens: input.estimatedTokens ?? countTextTokens(content),
+    };
+}
+const CLIP_MARKER = '\n[上下文片段因预算截断]';
+/**
+ * 按**渲染后**的 token 数收敛，而不是裸内容。
+ *
+ * ⚠️ 曾经的实现拿裸内容 token 判预算、外层却用 `renderedTokens()`（JSON 转义 + 信封）验收，
+ * 于是 `裸 token ≤ 预算 < 渲染 token` 这个窗口里 clip 会「认为放得下」原样返回，验收再不通过，
+ * 片段就被整段丢进 `omittedIds` —— `clippable` 形同虚设（`clippedIds` 恒空）。
+ * 窗口宽度 = 转义膨胀量，所以 **Windows 上尤其致命**：技能目录里每个 `\` 都要转义成 `\\`，
+ * 27 条技能的窗口从 POSIX 的 ~25 token 涨到 ~92 token，本仓库实测整份 `skills.catalog`
+ * （2643 token）在还剩 1900+ token 预算时被整个扔掉，模型完全看不到任何 Skill。
+ *
+ * 判据必须与验收同口径：这里直接对 `measure(候选内容)` 二分，measure 由调用方传入，
+ * 保证「算的就是最终要花的」。
+ */
+function clipToRenderedBudget(content, budgetTokens, measure) {
+    if (budgetTokens <= 0)
+        return '';
+    if (measure(content) <= budgetTokens)
+        return content;
+    // Token counter is deliberately dependency-free. Binary search preserves its
+    // exact mixed Chinese/ASCII estimate instead of falling back to chars/4.
+    let low = 0;
+    let high = content.length;
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        const candidate = `${content.slice(0, mid).trimEnd()}${CLIP_MARKER}`;
+        if (measure(candidate) <= budgetTokens)
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    if (low <= 0)
+        return '';
+    return `${content.slice(0, low).trimEnd()}${CLIP_MARKER}`;
+}
+export function renderContextFragment(fragment) {
+    const encoded = JSON.stringify(fragment.content)
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/&/g, '\\u0026');
+    return `<context-fragment id="${fragment.id}" kind="${fragment.kind}" authority="${fragment.authority}" encoding="json">\n${encoded}\n</context-fragment>`;
+}
+function renderedTokens(fragment) {
+    return countTextTokens(renderContextFragment(fragment));
+}
+/** 片段之间的分隔符——记账时必须与最终 join 用的是同一个常量。 */
+const FRAGMENT_SEPARATOR = '\n\n';
+const SEPARATOR_TOKENS = countTextTokens(FRAGMENT_SEPARATOR);
+/**
+ * Deterministic context budgeting. Required host facts are kept first; optional
+ * fragments compete by priority, then original order. No LLM call is involved.
+ */
+export function assembleContextBundle(input, budgetTokens = DEFAULT_TRANSIENT_BUDGET_TOKENS) {
+    const fragments = input.filter((fragment) => fragment.content.length > 0);
+    const indexed = fragments.map((fragment, index) => ({ fragment, index }));
+    const ordered = indexed.sort((a, b) => Number(Boolean(b.fragment.required)) - Number(Boolean(a.fragment.required))
+        || b.fragment.priority - a.fragment.priority
+        || a.index - b.index);
+    const included = [];
+    const omittedIds = [];
+    const clippedIds = [];
+    let remaining = Math.max(0, budgetTokens);
+    for (const item of ordered) {
+        const fragment = item.fragment;
+        // 片段之间要用 SEPARATOR 拼接，那几个 token 也得记账，否则最终 text 会超出预算
+        // （usedTokens > budgetTokens 会让 loop.ts::transientFor 的余量判断失真）。
+        const separator = included.length > 0 ? SEPARATOR_TOKENS : 0;
+        const budgetForItem = remaining - separator;
+        const fullTokens = renderedTokens(fragment);
+        if (fullTokens <= budgetForItem) {
+            included.push(item);
+            remaining -= fullTokens + separator;
+            continue;
+        }
+        if ((fragment.required || fragment.clippable) && budgetForItem > 24) {
+            // 同口径：二分时就按「这段内容渲染进本片段信封后要花多少 token」来量。
+            const content = clipToRenderedBudget(fragment.content, budgetForItem, (candidate) => renderedTokens({ ...fragment, content: candidate }));
+            const clipped = contextFragment({ ...fragment, content });
+            const clippedTokens = renderedTokens(clipped);
+            if (clipped.content && clippedTokens <= budgetForItem) {
+                included.push({ fragment: clipped, index: item.index });
+                if (clipped.content !== fragment.content)
+                    clippedIds.push(fragment.id);
+                remaining -= clippedTokens + separator;
+                continue;
+            }
+        }
+        omittedIds.push(fragment.id);
+    }
+    // Rendering follows semantic input order, not selection priority.
+    included.sort((a, b) => a.index - b.index);
+    const selected = included.map((item) => item.fragment);
+    const text = selected.map(renderContextFragment).join(FRAGMENT_SEPARATOR);
+    const usedTokens = countTextTokens(text);
+    return {
+        fragments: selected,
+        text,
+        diagnostics: {
+            budgetTokens,
+            usedTokens,
+            includedIds: selected.map((fragment) => fragment.id),
+            omittedIds,
+            clippedIds,
+        },
+    };
+}
+export function resizeContextBundle(bundle, budgetTokens) {
+    return assembleContextBundle(bundle.fragments, budgetTokens);
+}

package/src/context/contextBundle.ts

@@ -0,0 +1,176 @@
+import { countTextTokens } from './tokenCounter.js';
+
+export type ContextFragmentKind =
+  | 'runtime'
+  | 'persona'
+  | 'memory'
+  | 'episode'
+  | 'project'
+  | 'skill'
+  | 'plugin'
+  | 'task'
+  | 'diagnostic';
+
+export type ContextAuthority = 'host' | 'constraint' | 'user-evidence' | 'untrusted-data';
+
+export interface ContextFragment {
+  id: string;
+  kind: ContextFragmentKind;
+  authority: ContextAuthority;
+  priority: number;
+  estimatedTokens: number;
+  content: string;
+  required?: boolean;
+  clippable?: boolean;
+}
+
+export interface ContextBudgetDiagnostics {
+  budgetTokens: number;
+  usedTokens: number;
+  includedIds: string[];
+  omittedIds: string[];
+  clippedIds: string[];
+}
+
+export interface ContextBundle {
+  fragments: ContextFragment[];
+  text: string;
+  diagnostics: ContextBudgetDiagnostics;
+}
+
+export const DEFAULT_TRANSIENT_BUDGET_TOKENS = 3_000;
+
+export function contextFragment(
+  input: Omit<ContextFragment, 'estimatedTokens'> & { estimatedTokens?: number },
+): ContextFragment {
+  const content = input.content.trim();
+  return {
+    ...input,
+    content,
+    estimatedTokens: input.estimatedTokens ?? countTextTokens(content),
+  };
+}
+
+const CLIP_MARKER = '\n[上下文片段因预算截断]';
+
+/**
+ * 按**渲染后**的 token 数收敛，而不是裸内容。
+ *
+ * ⚠️ 曾经的实现拿裸内容 token 判预算、外层却用 `renderedTokens()`（JSON 转义 + 信封）验收，
+ * 于是 `裸 token ≤ 预算 < 渲染 token` 这个窗口里 clip 会「认为放得下」原样返回，验收再不通过，
+ * 片段就被整段丢进 `omittedIds` —— `clippable` 形同虚设（`clippedIds` 恒空）。
+ * 窗口宽度 = 转义膨胀量，所以 **Windows 上尤其致命**：技能目录里每个 `\` 都要转义成 `\\`，
+ * 27 条技能的窗口从 POSIX 的 ~25 token 涨到 ~92 token，本仓库实测整份 `skills.catalog`
+ * （2643 token）在还剩 1900+ token 预算时被整个扔掉，模型完全看不到任何 Skill。
+ *
+ * 判据必须与验收同口径：这里直接对 `measure(候选内容)` 二分，measure 由调用方传入，
+ * 保证「算的就是最终要花的」。
+ */
+function clipToRenderedBudget(
+  content: string,
+  budgetTokens: number,
+  measure: (candidate: string) => number,
+): string {
+  if (budgetTokens <= 0) return '';
+  if (measure(content) <= budgetTokens) return content;
+  // Token counter is deliberately dependency-free. Binary search preserves its
+  // exact mixed Chinese/ASCII estimate instead of falling back to chars/4.
+  let low = 0;
+  let high = content.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    const candidate = `${content.slice(0, mid).trimEnd()}${CLIP_MARKER}`;
+    if (measure(candidate) <= budgetTokens) low = mid;
+    else high = mid - 1;
+  }
+  if (low <= 0) return '';
+  return `${content.slice(0, low).trimEnd()}${CLIP_MARKER}`;
+}
+
+export function renderContextFragment(fragment: ContextFragment): string {
+  const encoded = JSON.stringify(fragment.content)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026');
+  return `<context-fragment id="${fragment.id}" kind="${fragment.kind}" authority="${fragment.authority}" encoding="json">\n${encoded}\n</context-fragment>`;
+}
+
+function renderedTokens(fragment: ContextFragment): number {
+  return countTextTokens(renderContextFragment(fragment));
+}
+
+/** 片段之间的分隔符——记账时必须与最终 join 用的是同一个常量。 */
+const FRAGMENT_SEPARATOR = '\n\n';
+const SEPARATOR_TOKENS = countTextTokens(FRAGMENT_SEPARATOR);
+
+/**
+ * Deterministic context budgeting. Required host facts are kept first; optional
+ * fragments compete by priority, then original order. No LLM call is involved.
+ */
+export function assembleContextBundle(
+  input: readonly ContextFragment[],
+  budgetTokens = DEFAULT_TRANSIENT_BUDGET_TOKENS,
+): ContextBundle {
+  const fragments = input.filter((fragment) => fragment.content.length > 0);
+  const indexed = fragments.map((fragment, index) => ({ fragment, index }));
+  const ordered = indexed.sort((a, b) =>
+    Number(Boolean(b.fragment.required)) - Number(Boolean(a.fragment.required))
+    || b.fragment.priority - a.fragment.priority
+    || a.index - b.index);
+  const included: Array<{ fragment: ContextFragment; index: number }> = [];
+  const omittedIds: string[] = [];
+  const clippedIds: string[] = [];
+  let remaining = Math.max(0, budgetTokens);
+
+  for (const item of ordered) {
+    const fragment = item.fragment;
+    // 片段之间要用 SEPARATOR 拼接，那几个 token 也得记账，否则最终 text 会超出预算
+    // （usedTokens > budgetTokens 会让 loop.ts::transientFor 的余量判断失真）。
+    const separator = included.length > 0 ? SEPARATOR_TOKENS : 0;
+    const budgetForItem = remaining - separator;
+    const fullTokens = renderedTokens(fragment);
+    if (fullTokens <= budgetForItem) {
+      included.push(item);
+      remaining -= fullTokens + separator;
+      continue;
+    }
+    if ((fragment.required || fragment.clippable) && budgetForItem > 24) {
+      // 同口径：二分时就按「这段内容渲染进本片段信封后要花多少 token」来量。
+      const content = clipToRenderedBudget(
+        fragment.content,
+        budgetForItem,
+        (candidate) => renderedTokens({ ...fragment, content: candidate }),
+      );
+      const clipped = contextFragment({ ...fragment, content });
+      const clippedTokens = renderedTokens(clipped);
+      if (clipped.content && clippedTokens <= budgetForItem) {
+        included.push({ fragment: clipped, index: item.index });
+        if (clipped.content !== fragment.content) clippedIds.push(fragment.id);
+        remaining -= clippedTokens + separator;
+        continue;
+      }
+    }
+    omittedIds.push(fragment.id);
+  }
+
+  // Rendering follows semantic input order, not selection priority.
+  included.sort((a, b) => a.index - b.index);
+  const selected = included.map((item) => item.fragment);
+  const text = selected.map(renderContextFragment).join(FRAGMENT_SEPARATOR);
+  const usedTokens = countTextTokens(text);
+  return {
+    fragments: selected,
+    text,
+    diagnostics: {
+      budgetTokens,
+      usedTokens,
+      includedIds: selected.map((fragment) => fragment.id),
+      omittedIds,
+      clippedIds,
+    },
+  };
+}
+
+export function resizeContextBundle(bundle: ContextBundle, budgetTokens: number): ContextBundle {
+  return assembleContextBundle(bundle.fragments, budgetTokens);
+}

package/src/context/contextLock.ts

@@ -0,0 +1,84 @@
+import { mkdir, readFile, rm, stat, utimes, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+const RETRY_MS = 200;
+const STALE_MS = 2 * 60_000;
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    // acquireContextLock 每 200ms 重试一次都会调用 sleep；listener 必须在正常
+    // 到点后摘掉，否则长等待会在同一个 AbortSignal 上线性堆积 listener。
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new Error('aborted while waiting for workspace context lock'));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // EPERM = 进程存在但不属于当前用户 → 算活（与 sessionRegistry/configFile 的
+    // processIsAlive 语义对齐）；判死会在共享机器上误抢别的用户的活锁。
+    return (e as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+async function stale(lockDir: string): Promise<boolean> {
+  try {
+    const info = await stat(lockDir);
+    if (Date.now() - info.mtimeMs <= STALE_MS) return false;
+    const raw = JSON.parse(await readFile(`${lockDir}/owner.json`, 'utf8')) as { pid?: unknown };
+    return typeof raw.pid !== 'number' || !pidAlive(raw.pid);
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Cross-process exclusive lock for one canonical context file. A heartbeat keeps
+ * long agent turns from looking stale; dead processes are recovered by PID.
+ */
+export async function acquireContextLock(
+  sessionFile: string,
+  signal?: AbortSignal,
+): Promise<() => Promise<void>> {
+  const lockDir = `${sessionFile}.lock`;
+  // 父目录（~/.minimal-agent/sessions/）通常早已存在（任何一个 cwd 聊过一轮就会由
+  // saveContext 递归建出来）；只有全新 HOME 的第一次交互恰好落在这条锁路径上时才会
+  // 缺失。用普通 mkdir(lockDir)（不带 recursive）是刻意的——EEXIST 是这把互斥锁的
+  // 判活信号（下面 catch 靠它识别"别人正持锁"），recursive:true 会让已存在的锁目录
+  // 也悄悄"创建成功"、互斥失效。故只把父目录单独递归建好，叶子目录仍走非 recursive
+  // 的 mkdir 以保留 EEXIST 语义。
+  while (true) {
+    signal?.throwIfAborted();
+    try {
+      await mkdir(dirname(lockDir), { recursive: true });
+      await mkdir(lockDir);
+      await writeFile(`${lockDir}/owner.json`, JSON.stringify({ pid: process.pid, startedAt: Date.now() }), 'utf8');
+      const heartbeat = setInterval(() => {
+        const now = new Date();
+        void utimes(lockDir, now, now).catch(() => {});
+      }, 30_000);
+      return async () => {
+        clearInterval(heartbeat);
+        await rm(lockDir, { recursive: true, force: true });
+      };
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== 'EEXIST') throw error;
+      if (await stale(lockDir)) {
+        await rm(lockDir, { recursive: true, force: true });
+        continue;
+      }
+      await sleep(RETRY_MS, signal);
+    }
+  }
+}

package/src/context/microCompactLite.ts

@@ -0,0 +1,218 @@
+/**
+ * ============================================================
+ *  src/context/microCompactLite.ts —— 工具结果微压缩（v2）
+ * ------------------------------------------------------------
+ *  对齐 kakadeai 的 microCompact 设计，纯规则实现，零 LLM 调用。
+ *
+ *  核心思路：
+ *    工具执行结果在写入 history 前经过一道"单向检查门"，
+ *    用规则压缩冗余内容，减少 token 消耗但不丢失关键信息。
+ *
+ *  对齐 kakadeai 的两条有效路径：
+ *    Path A: Cached MC → 本方案用 SHA-1 进程缓存 + 计数淘汰实现
+ *    Path B: Time-based MC → 本方案用轮次衰减实现
+ *
+ *  kakadeai 已删除 Legacy LLM path → 本方案不实现 LLM 压缩
+ * ============================================================
+ */
+
+import { createHash } from 'node:crypto';
+
+// ==================== 配置常量 ====================
+
+/** 同一内容最多原样保留多少次，之后用压缩引用替代 */
+const MAX_REPEAT_COUNT = 3;
+
+/** 触发截断的字符数阈值（仅白名单内的工具） */
+const MAX_RESULT_SIZE = 4000;
+
+/** 截断时保留的头部字符数 */
+const HEAD_KEEP_CHARS = 2000;
+
+/** 截断时保留的尾部字符数 */
+const TAIL_KEEP_CHARS = 1000;
+
+/** 时间衰减：条目首次出现后超过多少轮自动清理 */
+const MAX_KEEP_ROUNDS = 10;
+
+/** 短内容阈值：不超过此长度的内容直接放行（不做任何处理） */
+const SHORT_CONTENT_THRESHOLD = 200;
+
+// ==================== 类型定义 ====================
+
+interface CacheEntry {
+  /** 出现次数 */
+  count: number;
+  /** 首次出现的工具名（用于生成压缩提示） */
+  firstToolName: string;
+  /** 首次出现的轮次号（用于时间衰减判断） */
+  firstSeenTurn: number;
+}
+
+// ==================== Session 级状态 ====================
+/**
+ * 微压缩的运行时状态。模块级 defaultState 用于单进程场景（TUI / print），
+ * 多并发场景（HTTP server per-request）调 createMicroCompactState() 拿独立一份。
+ */
+export interface MicroCompactState {
+  turn: number;
+  cache: Map<string, CacheEntry>;
+}
+
+export function createMicroCompactState(): MicroCompactState {
+  return { turn: 0, cache: new Map() };
+}
+
+const defaultState: MicroCompactState = createMicroCompactState();
+
+export function incrementTurn(state: MicroCompactState = defaultState): void {
+  state.turn++;
+}
+
+export function resetTurn(state: MicroCompactState = defaultState): void {
+  state.turn = 0;
+}
+
+/** 缓存统计信息 */
+export interface MicroCompactStats {
+  totalEntries: number;
+  repeatedCount: number;
+  compressedCount: number;
+  expiredCount: number;
+  truncatedCount: number;
+  totalCharsSaved: number;
+}
+
+/** 获取当前缓存统计 */
+export function getCacheStats(state: MicroCompactState = defaultState): MicroCompactStats {
+  let compressedCount = 0;
+  let expiredCount = 0;
+  let truncatedCount = 0;
+  let totalCharsSaved = 0;
+  let repeatedCount = 0;
+
+  for (const entry of state.cache.values()) {
+    if (entry.count > 1) repeatedCount++;
+    if (entry.count > MAX_REPEAT_COUNT) {
+      compressedCount++;
+      totalCharsSaved += (entry.count - MAX_REPEAT_COUNT) * 500;
+    }
+    if (state.turn - entry.firstSeenTurn > MAX_KEEP_ROUNDS) {
+      expiredCount++;
+    }
+  }
+
+  return { totalEntries: state.cache.size, repeatedCount, compressedCount, expiredCount, truncatedCount, totalCharsSaved };
+}
+
+/** 清空缓存（供 /new 命令或测试使用） */
+export function clearCache(state: MicroCompactState = defaultState): void {
+  state.cache.clear();
+  state.turn = 0;
+}
+
+// ==================== 工具白名单 ====================
+/**
+ * 只有这些工具的返回值参与微压缩（长度截断 + SHA-1 去重）。
+ *
+ * 排除 Read/Edit/Write 的原因：输出本身就短，有独立的大小限制。
+ * 排除 WebSearch 的原因：搜索结果是"一次性知识注入"，首次必须完整展示给模型；
+ *   后续重复时由 SHA-1 去重处理，但不做长度截断（避免丢失关键信息）。
+ */
+const COMPRESSIBLE_TOOLS = new Set([
+  'Grep',
+  'Bash',
+  'WebFetch',
+  'Glob',
+]);
+
+// ==================== 核心函数 ====================
+
+/**
+ * 对一条工具执行结果进行微压缩处理。
+ *
+ * 这是整个模块唯一的对外接口。loop.ts 在把 tool_result 塞入 history 之前调用它。
+ *
+ * 处理流水线（按优先级）：
+ *   Rule 0: 错误/短内容 → 原样放行
+ *   Rule 1: SHA-1 去重 → 相同内容第 4 次起压缩为引用标记
+ *   Rule 2: 时间衰减 → 超过 N 轮未再出现的内容清理掉
+ *   Rule 3: 长度截断 → 白名单工具超长内容保留头尾 + 省略标记
+ *
+ * @param toolName 工具名
+ * @param content 工具返回的原始内容
+ * @returns 处理后的内容（可能被压缩、截断、或原样返回）
+ */
+export function microCompact(
+  toolName: string,
+  content: string,
+  state: MicroCompactState = defaultState,
+): string {
+  if (!content) return content;
+
+  // Rule 0: 错误信息原样保留
+  if (content.startsWith('Error:') || content.startsWith('错误')) {
+    return content;
+  }
+
+  // Rule 0b: 短内容直接放行
+  if (content.length <= SHORT_CONTENT_THRESHOLD) {
+    return content;
+  }
+
+  // Rule 1: SHA-1 去重
+  const hash = sha1(content);
+  const existing = state.cache.get(hash);
+
+  if (existing) {
+    existing.count++;
+    if (existing.count > MAX_REPEAT_COUNT) {
+      return `[↑ ${existing.firstToolName} 结果已重复出现 ${existing.count} 次（相同内容已省略）]`;
+    }
+    return content;
+  }
+
+  // 首次看到此内容
+  state.cache.set(hash, { count: 1, firstToolName: toolName, firstSeenTurn: state.turn });
+
+  // Rule 2: 不需要——首次出现不存在时间衰减问题
+
+  // Rule 3: 长度截断（仅白名单工具）
+  if (content.length > MAX_RESULT_SIZE && COMPRESSIBLE_TOOLS.has(toolName)) {
+    return truncateContent(content);
+  }
+
+  return content;
+}
+
+/**
+ * 清理过期条目（每轮开始前调用）。
+ * 将超过 MAX_KEEP_ROUNDS 未被再次访问的条目标记为过期，
+ * 后续如果这些条目的 hash 再次命中，会作为"新内容"重新计数。
+ */
+export function expireOldEntries(state: MicroCompactState = defaultState): number {
+  let expired = 0;
+  for (const [hash, entry] of state.cache) {
+    if (state.turn - entry.firstSeenTurn > MAX_KEEP_ROUNDS) {
+      state.cache.delete(hash);
+      expired++;
+    }
+  }
+  return expired;
+}
+
+// ==================== 内部函数 ====================
+
+function sha1(str: string): string {
+  return createHash('sha1').update(str).digest('hex');
+}
+
+function truncateContent(content: string): string {
+  const omitted = content.length - HEAD_KEEP_CHARS - TAIL_KEEP_CHARS;
+
+  return (
+    content.slice(0, HEAD_KEEP_CHARS) +
+    `\n\n[... 省略了 ${omitted.toLocaleString()} 字符 ...]\n\n` +
+    content.slice(-TAIL_KEEP_CHARS)
+  );
+}