minimal-agent 0.10.0 → 0.12.0

package/src/memory/turnJournal.js

@@ -0,0 +1,95 @@
+/**
+ * ============================================================
+ *  src/memory/turnJournal.ts —— 「一个用户回合」的会话原文记账
+ * ------------------------------------------------------------
+ *  把 user 输入与本回合最终 assistant 回答写进 `episodes/*.jsonl`，
+ *  给 `SearchConversations` 提供可检索的历史原文。
+ *
+ *  ★ 为什么是独立模块、而不是塞进 loop.ts：
+ *    `runQuery` 不等于「一个用户回合」——子 Agent（tools/agent/agent.ts 直接调
+ *    runQuery，且**携带同一份 workspaceId/sessionId**）和 workflow 的每个 llm/agent 步
+ *    都会各调一次 runQuery。记在那里会把子任务提示词当成「用户说的话」灌进历史检索，
+ *    污染的正是这个功能要保护的东西。
+ *
+ *    也不能只留在 `session/runTurn.ts`：TUI 走的是 `ui/hooks/useChat.ts` → runWithPlugins，
+ *    **根本不经过 runTurn**。此前的后果是 TUI 对话永远不入库，而一次性的
+ *    `.backfill-<ws>.json` 标记又让 SearchConversations 在首次搜索后永久停更 ——
+ *    工具宣称"搜索本机历史会话原文"，实际对 TUI 用户静默失效。
+ *
+ *    所以：实现只有这一份，调用点恰好落在两个真正的「用户回合」边界上
+ *    （runTurn 与 useChat.submit），子 Agent 与 workflow 步一概不记。
+ * ============================================================
+ */
+import { applyEpisodeRetention, episodicMemoryService, finishRetentionSweep, shouldSweepRetention, } from './episodicMemory.js';
+import { memoryService } from './memoryService.js';
+function messageText(message) {
+    if (typeof message.content === 'string')
+        return message.content;
+    if (!Array.isArray(message.content))
+        return '';
+    return message.content
+        .filter((part) => part.type === 'text')
+        .map((part) => part.text)
+        .join('\n');
+}
+function lastAssistantMessage(messages, start) {
+    for (let index = messages.length - 1; index >= start; index -= 1) {
+        if (messages[index]?.role === 'assistant')
+            return messages[index];
+    }
+    return undefined;
+}
+/**
+ * 会话原文的保留清理：节流后台执行，绝不阻塞本回合。
+ * 与 `clipboardImage::pruneOldTempImages` 同款 fire-and-forget，不需要常驻定时器。
+ */
+function sweepRetentionInBackground(workspaceId) {
+    if (!shouldSweepRetention(workspaceId))
+        return;
+    void (async () => {
+        try {
+            const settings = await memoryService.settings();
+            if (!settings.retention)
+                return;
+            await applyEpisodeRetention(workspaceId, settings.retention);
+        }
+        finally {
+            finishRetentionSweep(workspaceId);
+        }
+    })().catch(() => undefined);
+}
+/**
+ * 开一次回合记账。缺权限 / 缺 workspaceId / 缺 sessionId 都返回 null（不记，也不报错）——
+ * 记账是附加能力，绝不能反过来阻断对话。
+ */
+export async function startTurnJournal(input) {
+    const context = input.memoryContext;
+    // 判据是 `!== 'denied'`：只要宿主没有明确拒绝记忆访问就记账，`read-only` 也照记。
+    // 这是**有意放松**的（2026-08-13 明确决定：优先保证检索效果与性能）——收紧成"只有可写
+    // 权限才记"会让 `-p`（默认 read-only）和部分 Desktop 场景的历史检索大面积失效。
+    // 真正的隐私边界由 `denied` 与保留窗口（MemorySettings.retention）负责，不靠这里收窄。
+    if (!context || context.access === 'denied' || !context.workspaceId || !context.sessionId) {
+        return null;
+    }
+    const target = { workspaceId: context.workspaceId, sessionId: context.sessionId };
+    await episodicMemoryService.append({
+        ...target,
+        role: 'user',
+        content: input.userInput,
+        ...(input.userMessageId ? { messageId: input.userMessageId } : {}),
+    }).catch(() => undefined);
+    sweepRetentionInBackground(target.workspaceId);
+    return {
+        async finish(history, startIndex) {
+            const assistant = lastAssistantMessage(history, startIndex);
+            const content = assistant ? messageText(assistant) : '';
+            if (!content)
+                return;
+            await episodicMemoryService.append({
+                ...target,
+                role: 'assistant',
+                content,
+            }).catch(() => undefined);
+        },
+    };
+}

package/src/memory/turnJournal.ts

@@ -0,0 +1,120 @@
+/**
+ * ============================================================
+ *  src/memory/turnJournal.ts —— 「一个用户回合」的会话原文记账
+ * ------------------------------------------------------------
+ *  把 user 输入与本回合最终 assistant 回答写进 `episodes/*.jsonl`，
+ *  给 `SearchConversations` 提供可检索的历史原文。
+ *
+ *  ★ 为什么是独立模块、而不是塞进 loop.ts：
+ *    `runQuery` 不等于「一个用户回合」——子 Agent（tools/agent/agent.ts 直接调
+ *    runQuery，且**携带同一份 workspaceId/sessionId**）和 workflow 的每个 llm/agent 步
+ *    都会各调一次 runQuery。记在那里会把子任务提示词当成「用户说的话」灌进历史检索，
+ *    污染的正是这个功能要保护的东西。
+ *
+ *    也不能只留在 `session/runTurn.ts`：TUI 走的是 `ui/hooks/useChat.ts` → runWithPlugins，
+ *    **根本不经过 runTurn**。此前的后果是 TUI 对话永远不入库，而一次性的
+ *    `.backfill-<ws>.json` 标记又让 SearchConversations 在首次搜索后永久停更 ——
+ *    工具宣称"搜索本机历史会话原文"，实际对 TUI 用户静默失效。
+ *
+ *    所以：实现只有这一份，调用点恰好落在两个真正的「用户回合」边界上
+ *    （runTurn 与 useChat.submit），子 Agent 与 workflow 步一概不记。
+ * ============================================================
+ */
+
+import {
+  applyEpisodeRetention,
+  episodicMemoryService,
+  finishRetentionSweep,
+  shouldSweepRetention,
+} from './episodicMemory.js';
+import { memoryService } from './memoryService.js';
+import type { Message } from '../types.js';
+
+export interface TurnJournalInput {
+  memoryContext?: {
+    access?: string;
+    workspaceId?: string;
+    sessionId?: string;
+  };
+  userInput: string;
+  userMessageId?: string;
+}
+
+export interface TurnJournal {
+  /** 回合收尾时调用：从 history 里取本回合最后一条 assistant 消息入库。 */
+  finish(history: readonly Message[], startIndex: number): Promise<void>;
+}
+
+function messageText(message: Message): string {
+  if (typeof message.content === 'string') return message.content;
+  if (!Array.isArray(message.content)) return '';
+  return message.content
+    .filter((part): part is Extract<typeof part, { type: 'text' }> => part.type === 'text')
+    .map((part) => part.text)
+    .join('\n');
+}
+
+function lastAssistantMessage(
+  messages: readonly Message[],
+  start: number,
+): Message | undefined {
+  for (let index = messages.length - 1; index >= start; index -= 1) {
+    if (messages[index]?.role === 'assistant') return messages[index];
+  }
+  return undefined;
+}
+
+/**
+ * 会话原文的保留清理：节流后台执行，绝不阻塞本回合。
+ * 与 `clipboardImage::pruneOldTempImages` 同款 fire-and-forget，不需要常驻定时器。
+ */
+function sweepRetentionInBackground(workspaceId: string): void {
+  if (!shouldSweepRetention(workspaceId)) return;
+  void (async () => {
+    try {
+      const settings = await memoryService.settings();
+      if (!settings.retention) return;
+      await applyEpisodeRetention(workspaceId, settings.retention);
+    } finally {
+      finishRetentionSweep(workspaceId);
+    }
+  })().catch(() => undefined);
+}
+
+/**
+ * 开一次回合记账。缺权限 / 缺 workspaceId / 缺 sessionId 都返回 null（不记，也不报错）——
+ * 记账是附加能力，绝不能反过来阻断对话。
+ */
+export async function startTurnJournal(
+  input: TurnJournalInput,
+): Promise<TurnJournal | null> {
+  const context = input.memoryContext;
+  // 判据是 `!== 'denied'`：只要宿主没有明确拒绝记忆访问就记账，`read-only` 也照记。
+  // 这是**有意放松**的（2026-08-13 明确决定：优先保证检索效果与性能）——收紧成"只有可写
+  // 权限才记"会让 `-p`（默认 read-only）和部分 Desktop 场景的历史检索大面积失效。
+  // 真正的隐私边界由 `denied` 与保留窗口（MemorySettings.retention）负责，不靠这里收窄。
+  if (!context || context.access === 'denied' || !context.workspaceId || !context.sessionId) {
+    return null;
+  }
+  const target = { workspaceId: context.workspaceId, sessionId: context.sessionId };
+  await episodicMemoryService.append({
+    ...target,
+    role: 'user',
+    content: input.userInput,
+    ...(input.userMessageId ? { messageId: input.userMessageId } : {}),
+  }).catch(() => undefined);
+  sweepRetentionInBackground(target.workspaceId);
+
+  return {
+    async finish(history, startIndex) {
+      const assistant = lastAssistantMessage(history, startIndex);
+      const content = assistant ? messageText(assistant) : '';
+      if (!content) return;
+      await episodicMemoryService.append({
+        ...target,
+        role: 'assistant',
+        content,
+      }).catch(() => undefined);
+    },
+  };
+}

package/src/memory/types.js

@@ -0,0 +1,2 @@
+export const MEMORY_REVIEW_DAYS_MIN = 7;
+export const MEMORY_REVIEW_DAYS_MAX = 3_650;

package/src/memory/types.ts

@@ -0,0 +1,186 @@
+export type MemoryScope = 'personal' | 'workspace';
+export type MemoryEvidence = 'user_stated' | 'user_confirmed';
+export type MemorySensitivity = 'normal' | 'sensitive';
+export type MemoryCategory =
+  | 'profile'
+  | 'preference'
+  | 'topic'
+  | 'person'
+  | 'project'
+  | 'decision';
+export type MemoryStatus = 'active' | 'needs_review' | 'superseded';
+export type MemoryVersion = string;
+
+export const MEMORY_REVIEW_DAYS_MIN = 7;
+export const MEMORY_REVIEW_DAYS_MAX = 3_650;
+
+/**
+ * The original fields remain required for desktop and npm compatibility.
+ * V2 lifecycle fields are optional so old protocol clients and hand-written
+ * Markdown records continue to deserialize without a flag day migration.
+ */
+export interface MemoryRecord {
+  id: string;
+  scope: MemoryScope;
+  workspaceId?: string;
+  category: MemoryCategory;
+  subject: string;
+  statement: string;
+  evidence: MemoryEvidence;
+  evidenceQuote: string;
+  sourceSessionId: string;
+  sourceMessageId: string;
+  sensitivity: MemorySensitivity;
+  createdAt: number;
+  updatedAt: number;
+  schemaVersion?: 2;
+  topicKey?: string;
+  aliases?: string[];
+  status?: MemoryStatus;
+  revision?: number;
+  lastConfirmedAt?: number;
+  supersedesIds?: string[];
+  evidenceHash?: string;
+}
+
+export interface MemoryRecordV2 extends MemoryRecord {
+  schemaVersion: 2;
+  topicKey: string;
+  aliases: string[];
+  status: MemoryStatus;
+  revision: number;
+  lastConfirmedAt: number;
+  supersedesIds: string[];
+}
+
+export interface VersionedMemoryRecord {
+  record: MemoryRecordV2;
+  version: MemoryVersion;
+}
+
+export type MemoryEditablePatch = Partial<
+  Pick<MemoryRecord, 'category' | 'subject' | 'statement' | 'aliases'>
+>;
+
+export interface MemoryReviewWindows {
+  profile: number;
+  preference: number;
+  topic: number;
+  person: number;
+  project: number;
+  decision: number;
+}
+
+/**
+ * 会话原文日志（`episodes/*.jsonl`）的保留窗口。
+ *
+ * 记忆条目（records）是用户明确授权保存的稳定事实，只有用户能删；会话原文日志是为了
+ * `SearchConversations` 而留的**全量对话副本**，性质完全不同——它必须有保留上限，否则
+ * 明文对话会无限累积（仓库里其它 append-only 存储都有清理，只有它没有）。
+ */
+export interface MemoryRetention {
+  /** 超过这个天数的会话原文自动清理。 */
+  episodeDays: number;
+  /** 单个工作区的会话原文总体积上限（MB），先到者先触发。 */
+  episodeMaxMegabytes: number;
+}
+
+export interface MemorySettings {
+  autoRemember: boolean;
+  /** Optional on the public wire type for pre-v2 desktop clients. */
+  reviewAfterDays?: MemoryReviewWindows;
+  /** Optional on the wire so pre-retention clients keep deserializing. */
+  retention?: MemoryRetention;
+}
+
+export interface MemoryDiagnostic {
+  path: string;
+  message: string;
+}
+
+export interface MemorySnapshot {
+  records: MemoryRecordV2[];
+  versions: Record<string, MemoryVersion>;
+  diagnostics: MemoryDiagnostic[];
+  createdAt: number;
+}
+
+export interface PersonaDocument {
+  content: string;
+  evidenceQuote: string;
+  sourceSessionId: string;
+  sourceMessageId: string;
+  updatedAt: number;
+  revision?: number;
+}
+
+export interface PersonaInput {
+  content: string;
+  evidenceQuote: string;
+  sourceSessionId: string;
+  sourceMessageId: string;
+}
+
+export interface VersionedPersonaDocument {
+  persona: PersonaDocument;
+  version: MemoryVersion;
+}
+
+export interface VersionedMemorySettings {
+  settings: MemorySettings;
+  version: MemoryVersion;
+}
+
+export type MemoryUpdate = Partial<
+  Pick<
+    MemoryRecord,
+    | 'category'
+    | 'subject'
+    | 'statement'
+    | 'evidence'
+    | 'evidenceQuote'
+    | 'sourceSessionId'
+    | 'sourceMessageId'
+    | 'sensitivity'
+    | 'aliases'
+    | 'status'
+    | 'supersedesIds'
+  >
+>;
+
+export interface MemoryContextBundle {
+  text: string;
+  snapshot: MemorySnapshot;
+  includedIds: string[];
+  estimatedTokens: number;
+  sections: Array<{
+    id: 'persona' | 'preferences' | 'relevant' | 'health';
+    content: string;
+    includedIds: string[];
+    estimatedTokens: number;
+  }>;
+}
+
+export interface ConversationEpisode {
+  id: string;
+  workspaceId: string;
+  sessionId: string;
+  messageId: string;
+  role: 'user' | 'assistant';
+  content: string;
+  createdAt: number;
+  contentHash: string;
+}
+
+export interface ConversationSearchOptions {
+  workspaceId: string;
+  sessionId?: string;
+  limit?: number;
+  scope?: 'workspace' | 'all';
+  explicitCrossWorkspace?: boolean;
+}
+
+export interface ConversationSearchResult extends ConversationEpisode {
+  score: number;
+  snippet: string;
+}

package/src/messageQueue.ts

@@ -0,0 +1,123 @@
+/**
+ * ============================================================
+ *  src/messageQueue.ts —— 用户输入队列（支持优先级）
+ * ------------------------------------------------------------
+ *  实现对话进行中用户插话的排队管理。
+ *
+ *  设计原则：
+ *    - 极简：只保留 minimal-agent 需要的核心功能
+ *    - 发布订阅：subscribe() 订阅队列变化，用于UI更新
+ *    - 工厂函数：createInputQueue() 创建独立实例，支持多session/测试
+ *    - 两级优先级：'now'（立即处理）> 'next'（排队等待）
+ * ============================================================
+ */
+
+export type QueuePriority = 'now' | 'next';
+
+export interface QueuedInput {
+  id: string;
+  value: string;
+  priority: QueuePriority;
+  timestamp: number;
+}
+
+export interface InputQueue {
+  enqueue(value: string, priority?: QueuePriority): void;
+  dequeue(): QueuedInput | undefined;
+  dequeueAll(): QueuedInput[];
+  peek(): QueuedInput | undefined;
+  clear(): void;
+  size(): number;
+  subscribe(callback: () => void): () => void;
+  getSnapshot(): readonly QueuedInput[];
+}
+
+function randomUUID(): string {
+  if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+    return crypto.randomUUID();
+  }
+  return `q_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+
+export function createInputQueue(): InputQueue {
+  const queue: QueuedInput[] = [];
+  const subscribers = new Set<() => void>();
+
+  function notify(): void {
+    for (const cb of subscribers) {
+      cb();
+    }
+  }
+
+  function findBestIndex(): number {
+    let bestIdx = 0;
+    let bestPrio = 99;
+    for (let i = 0; i < queue.length; i++) {
+      const p = queue[i]!.priority === 'now' ? 0 : 1;
+      if (p < bestPrio) {
+        bestPrio = p;
+        bestIdx = i;
+      }
+    }
+    return bestIdx;
+  }
+
+  return {
+    enqueue(value, priority = 'next') {
+      queue.push({
+        id: randomUUID(),
+        value,
+        priority,
+        timestamp: Date.now(),
+      });
+      notify();
+    },
+
+    dequeue() {
+      if (queue.length === 0) return undefined;
+      const bestIdx = findBestIndex();
+      const item = queue.splice(bestIdx, 1)[0];
+      if (item) notify();
+      return item;
+    },
+
+    dequeueAll() {
+      if (queue.length === 0) return [];
+      const sorted = [...queue].sort((a, b) => {
+        const pa = a.priority === 'now' ? 0 : 1;
+        const pb = b.priority === 'now' ? 0 : 1;
+        if (pa !== pb) return pa - pb;
+        return a.timestamp - b.timestamp;
+      });
+      queue.length = 0;
+      notify();
+      return sorted;
+    },
+
+    peek() {
+      if (queue.length === 0) return undefined;
+      return queue[findBestIndex()];
+    },
+
+    clear() {
+      if (queue.length === 0) return;
+      queue.length = 0;
+      notify();
+    },
+
+    size() {
+      return queue.length;
+    },
+
+    subscribe(callback) {
+      subscribers.add(callback);
+      return () => {
+        subscribers.delete(callback);
+      };
+    },
+
+    getSnapshot() {
+      return Object.freeze([...queue]);
+    },
+  };
+}