@yandy0725/memory-core 1.0.1 → 2.0.1

package/src/injection.ts

@@ -217,13 +217,14 @@ export async function scanEntries(store: MemoryStore): Promise<EntryManifest[]>
 		.slice(0, SIDE_QUERY_MAX_ENTRIES);
 }
 
-export async function renderSurfacedBlock(
+export async function renderSurfacedEntries(
 	store: MemoryStore,
 	selectedFiles: string[],
 	maxEntryBytes: number,
 	maxInjectionBytes: number,
-): Promise<string> {
+): Promise<{ files: string[]; content: string }> {
 	const blocks: string[] = [];
+	const files: string[] = [];
 	let totalBytes = 0;
 
 	for (const file of selectedFiles) {
@@ -239,13 +240,26 @@ export async function renderSurfacedBlock(
 		const blockBytes = Buffer.byteLength(block, "utf8");
 		if (totalBytes + blockBytes > maxInjectionBytes) break;
 		blocks.push(block);
+		files.push(file);
 		totalBytes += blockBytes;
 	}
 
-	if (blocks.length === 0) return "";
-	return `<relevant_memories>\n${blocks.join("\n\n")}\n</relevant_memories>`;
+	if (blocks.length === 0) return { files: [], content: "" };
+	return { files, content: `<relevant_memories>\n${blocks.join("\n\n")}\n</relevant_memories>` };
 }
 
+/**
+ * 单块渲染的兼容入口：只返回渲染文本。
+ * 该签名是既有公开契约，保留为 `renderSurfacedEntries` 的薄壳。
+ */
+export const renderSurfacedBlock = (
+	store: MemoryStore,
+	selectedFiles: string[],
+	maxEntryBytes: number,
+	maxInjectionBytes: number,
+): Promise<string> =>
+	renderSurfacedEntries(store, selectedFiles, maxEntryBytes, maxInjectionBytes).then((r) => r.content);
+
 /** Build the side-query task prompt. */
 export function buildSideQueryTask(manifest: EntryManifest[], userPrompt: string, maxFiles: number): string {
 	// `Math.max(1, …)`：空清单不会走到这里（侧查询先返回 []），但除零会得到 Infinity。

package/src/orchestration/conversation.ts

@@ -4,7 +4,7 @@ import type { ExtractMessage } from "./ports.js";
  * 对话渲染：把中立的 `ExtractMessage` 序列压成 extract prompt 里的那一段文本，
  * 并在超出预算时做「首尾优先、中段裁减」。
  *
- * 与 `prompts.ts` 分开是为了不打环：prompt 文本依赖渲染结果，而 `runExtract` 依赖 prompt 文本。
+ * 与 `prompts.ts` 分开是为了不打环：prompt 文本依赖渲染结果，而 extract 描述符依赖 prompt 文本。
  */
 
 export interface ConversationLimits {

package/src/orchestration/dream.ts

@@ -1,82 +1,40 @@
-import { readdir } from "node:fs/promises";
-import { join } from "node:path";
-import type { SessionPersistenceConfig } from "../config.js";
-import { BACKUP_DIR, type MemoryStore } from "../store/memory-store.js";
-import { createSnapshot } from "../store/snapshot.js";
-import { isReservedWindowsName } from "../store/windows-names.js";
 import { DREAM_ACTIONS } from "../tool/actions.js";
 import { buildDreamTask } from "./prompts.js";
-import type { HeadlessAgentPort } from "./ports.js";
+import type { MemoryTask } from "./task.js";
 
-export interface RunDreamOpts {
-	/** 必填：模型来自显式配置（启动校验已保证可解析），没有父模型回退。 */
-	model: string;
-	/** 宿主的思考/推理档位。core 不解释，原样透传给端口。 */
-	effort?: string;
-	memoryDir: string;
-	/** 唯一写入通道。dream 的整轮互斥与快照都挂在它上面。 */
-	store: MemoryStore;
-	/** 索引行数硬上限（= `config.memIndexMaxLines`），写进 prompt 让 dream 承担容量管理。 */
-	maxLines: number;
-	sessionPersistence?: SessionPersistenceConfig;
+/** `incomplete` / `not-run` 的短诊断：`cause`，`not-run` 带上 `detail`。 */
+function describeCause(why: { cause: string; detail?: string }): string {
+	return why.detail ? `${why.cause} (${why.detail})` : why.cause;
 }
 
-async function snapshotFiles(memoryDir: string, platform: NodeJS.Platform = process.platform): Promise<string[]> {
-	const entries = await readdir(memoryDir, { withFileTypes: true }).catch(() => []);
-	return (
-		entries
-			.filter((entry) => entry.isFile() && !entry.name.startsWith("."))
-			// win32：保留设备名文件按名打开会命中设备（CON 等），`createSnapshot` 的 cp 会失败；
-			// dream 是 fail-closed 的，一次 cp 失败就打断整轮（与 `MemoryStore` 的 `#entryFiles` 同一契约）。
-			.filter((entry) => !(platform === "win32" && isReservedWindowsName(entry.name)))
-			.map((entry) => entry.name)
-			.sort()
-	);
-}
-
-/**
- * 跑一轮 dream：整轮持有进程内逻辑锁 → 对整目录拍一次快照 → 起一个只有 `memory` 工具的
- * headless 会话。
- *
- * 整轮持锁是刻意的：dream 的多次 `replace` / `remove` 必须对同进程的 `memory add` 与 extract
- * 呈现为**一个**原子区间，否则用户会在 dream 中途读到半合并的状态。锁在进程内（不是 `.lock`），
- * 所以跨进程的其它 worktree 仍能正常写入 —— 它们的每次物理写入只被挡毫秒级。
- *
- * 其内部的每个原语调用必须带 `{ skipLogicalLock: true, skipSnapshot: true }`（由 `memoryTool`
- * 请求字段表达，适配层据此构造子会话的工具），否则它们会去抢自己已持有的锁而自锁到超时，
- * 并且会为同一批变更各拍一次快照。
- */
-
-export async function runDream(opts: RunDreamOpts, ports: { headless: HeadlessAgentPort }): Promise<string> {
-	return opts.store.withLogicalLock(async () => {
-		// 启动自检：忘了包 withLogicalLock 会静默失去整轮互斥。
-		if (!opts.store.logicalLockActive()) {
-			throw new Error("dream must run under the memory logical lock");
+/** dream 描述符：core 自读 `cfg.memIndexMaxLines`，适配层只给触发点与端口。 */
+export const dream: MemoryTask<Record<string, never>, string> = {
+	id: "dream",
+	plan: {
+		timeoutMs: 600_000,
+		memoryTool: DREAM_ACTIONS,
+		lock: "logical+snapshot",
+		errorPolicy: "rethrow",
+	},
+	buildPrompt(cfg) {
+		return buildDreamTask(cfg.memIndexMaxLines);
+	},
+	parse(_cfg, _deps, _input, text) {
+		return text;
+	},
+	notCompleted(_cfg, _deps, _input, why) {
+		switch (why.status) {
+			case "no-input":
+				// 理论不可达（dream 的 prompt 恒有值），但用户显式触发的任务不许静默报成功。
+				throw new Error("dream has no input to work with");
+			case "lock-busy":
+				throw new Error("the dream round could not start: the memory logical lock is busy");
+			case "no-output":
+				throw new Error("the host ran the dream round but produced no summary");
+			case "incomplete":
+			case "not-run":
+				throw new Error(`the dream round did not complete (${describeCause(why)})`);
 		}
+	},
+};
 
-		// 进入时对整目录拍一次快照；这一轮里各原语的逐文件快照被 skipSnapshot 跳过。
-		const files = await snapshotFiles(opts.memoryDir, opts.store.cfg.platform);
-		await createSnapshot(join(opts.memoryDir, BACKUP_DIR), "dream", files, opts.memoryDir, {
-			keep: opts.store.cfg.lock.snapshotKeep,
-			platform: opts.store.cfg.platform,
-		});
-
-		const result = await ports.headless.run({
-			task: buildDreamTask(opts.maxLines),
-			cwd: opts.memoryDir,
-			model: opts.model,
-			effort: opts.effort,
-			maxTurns: undefined,
-			timeoutMs: 600_000,
-			// 没有裸写权限：dream 的重构能力边界由 7 个原语定义，因此首次可被单测覆盖。
-			builtinTools: "none",
-			// dream 专属的 7 个 action；整轮持锁与进入时的全目录快照都在外面，所以两个 skip 都开。
-			memoryTool: { actions: DREAM_ACTIONS, skipLogicalLock: true, skipSnapshot: true },
-			sessionPersistence: opts.sessionPersistence,
-		});
-		// `null` = 宿主没跑这一轮。dream 是用户显式触发的（`/dream` 或 nudge 确认后），
-		// 静默返回空摘要会让用户以为合并成功了 —— 显式抛错，由适配层转成失败通知。
-		if (result === null) throw new Error("the host did not run the dream round");
-		return result;
-	});
-}

package/src/orchestration/extract.ts

@@ -1,75 +1,60 @@
-import type { SessionPersistenceConfig } from "../config.js";
-import type { MemoryStore } from "../store/memory-store.js";
 import { MAIN_AGENT_ACTIONS, type MemoryAction } from "../tool/actions.js";
 import { buildExtractTask } from "./prompts.js";
-import type { HeadlessAgentPort, HostTranscriptPort } from "./ports.js";
+import type { MemoryTask } from "./task.js";
 
-export interface RunExtractOpts {
-	/** 必填：模型来自显式配置（启动校验已保证可解析），没有父模型回退。 */
-	model: string;
-	/** 宿主的思考/推理档位。core 不解释，原样透传给端口。 */
-	effort?: string;
-	memoryDir: string;
-	/** 唯一写入通道：extract 的整轮互斥挂在它的 `tryWithLogicalLock` 上。 */
-	store: MemoryStore;
-	/** 宿主的原始消息序列（pi 的 `AgentMessage[]` 等），经 `ports.transcript` 转成中立形状。 */
+/** `runTask(TASKS.extractMemories, …)` 的输入：宿主只给数据，预算由 core 从 `cfg` 自读。 */
+export interface ExtractInput {
 	messages: unknown[];
-	maxContextTokens: number;
-	maxToolResultChars: number;
-	maxAssistantChars: number;
-	sessionPersistence?: SessionPersistenceConfig;
-	agentsMdBlocks?: string[];
-	/**
-	 * 子会话里的 `memory` 工具每成功写入一条就回调一次。
-	 *
-	 * extract 跑在 headless 子会话里，适配层看不到它写了几条，只能靠这个回调计数（用来决定
-	 * 要不要弹「Extracted N memories」）。core 不解释它，只负责透到工具规格里。
-	 */
+	agentsMdBlocks: string[];
 	onWrite?: (info: { action: MemoryAction; name?: string }) => void;
 }
 
-export interface ExtractPorts {
-	headless: HeadlessAgentPort;
-	transcript: HostTranscriptPort;
+export interface ExtractResult {
+	skipped: boolean;
+	result?: string;
 }
 
-/**
- * 跑一轮 extract。
- *
- * **不等待逻辑锁**：拿不到就跳过本轮并返回 `{ skipped: true }`。extract 在每轮结束都触发，
- * 让它排队等 dream（分钟级）只会把一批批早已过时的对话堆在队列里，等 dream 结束后依次重放。
- *
- * 错误**不吞**：吞掉会让 extract 的失败对用户完全不可见。由调用方决定如何呈现（适配层通常
- * 做限流通知）。
- */
-export async function runExtract(
-	opts: RunExtractOpts,
-	ports: ExtractPorts,
-): Promise<{ skipped: boolean; result?: string }> {
-	const messages = ports.transcript.toExtractMessages(opts.messages);
-	if (messages.length === 0) return { skipped: true };
-
-	const task = buildExtractTask(messages, opts.maxContextTokens, opts.agentsMdBlocks ?? [], {
-		maxToolResultChars: opts.maxToolResultChars,
-		maxAssistantChars: opts.maxAssistantChars,
-	});
-
-	const result = await opts.store.tryWithLogicalLock(() =>
-		ports.headless.run({
-			task,
-			cwd: opts.memoryDir,
-			model: opts.model,
-			effort: opts.effort,
-			maxTurns: 5,
-			timeoutMs: 120_000,
-			// 没有文件工具：extract 只能通过 memory 原语写。
-			builtinTools: "none",
-			memoryTool: { actions: MAIN_AGENT_ACTIONS, skipLogicalLock: true, onWrite: opts.onWrite },
-			sessionPersistence: opts.sessionPersistence,
-		}),
-	);
-
-	if (result === null) return { skipped: true };
-	return { skipped: false, result };
-}
+/** extractMemories 描述符：core 自读 `cfg.extractMemories` 的预算，适配层只给宿主数据。 */
+export const extractMemories: MemoryTask<ExtractInput, ExtractResult> = {
+	id: "extractMemories",
+	plan: {
+		maxTurns: 5,
+		timeoutMs: 120_000,
+		memoryTool: MAIN_AGENT_ACTIONS,
+		lock: "logical",
+		errorPolicy: "rethrow",
+	},
+	buildPrompt(cfg, deps, input) {
+		if (!deps.transcript) throw new Error("the extract task requires a transcript port");
+		const messages = deps.transcript.toExtractMessages(input.messages);
+		// 「判空在锁之前」由 `runTask` 的顺序契约保证（buildPrompt 先于 plan.lock 执行），
+		// 这里只做纯计算，不碰 store / lock。
+		if (messages.length === 0) return null;
+		return buildExtractTask(messages, cfg.extractMemories.maxContextTokens, input.agentsMdBlocks, {
+			maxToolResultChars: cfg.extractMemories.maxToolResultChars,
+			maxAssistantChars: cfg.extractMemories.maxAssistantChars,
+		});
+	},
+	parse(_cfg, _deps, _input, text) {
+		return { skipped: false, result: text };
+	},
+	notCompleted(_cfg, _deps, _input, why) {
+		switch (why.status) {
+			case "no-input":
+			case "lock-busy":
+			case "not-run":
+				return { skipped: true };
+			case "no-output":
+				// pi 的空回复一直是 `{ skipped: false, result: "" }`：这一轮确实跑完、只是没写出文本，
+				// 得让「Extracted N memories」通知的既有语义活下来。
+				return { skipped: false, result: "" };
+			case "incomplete":
+				// 写入可能已经通过子会话工具发生过：报失败会歪曲一个确实落盘了的轮次。
+				return { skipped: false };
+		}
+	},
+	memoryToolHooks(input) {
+		return { onWrite: input.onWrite };
+	},
+};
 

package/src/orchestration/ports.ts

@@ -8,11 +8,30 @@ import type { MemoryAction } from "../tool/actions.js";
  */
 
 /**
- * 跑一轮受限工具的 headless 会话，返回 assistant 文本。
+ * 一轮 headless 会话的结果。
  *
- * `null` = 本轮**未执行**（宿主拒绝、超时、或适配层判定不该跑）。调用方必须能区分
- * 「跑了但没写出东西」与「根本没跑」：`runExtract` 靠它决定要不要报 `{ skipped: true }`。
+ * **判别规则**：请求**发出之前**就结束 → `not-run`（没跑）；**发出之后**没拿到完整文本 →
+ * `incomplete`（跑过一部分，写入可能已发生）。`no-output` 是「跑完但终止事件没有任何 assistant
+ * 文本」—— 它是 `incomplete` 的极端形态，单独留一个 arm 是因为调用方对「跑了、没写出东西」与
+ * 「写了半截」的处置不同。
  */
+export type HeadlessOutcome =
+	/** 跑完并拿到了最终文本。空回复是 `text: ""`，**不是** `no-output`。 */
+	| { status: "completed"; text: string }
+	/** 跑过但拿不到最终文本（终止事件无 assistant 输出）。 */
+	| { status: "no-output" }
+	/** 跑过一部分：写入可能已发生。`aborted` 指请求已发出、中途被取消。 */
+	| { status: "incomplete"; cause: "max-tokens" | "turn-limit" | "aborted" }
+	/**
+	 * 请求从未真正开始：宿主拒绝、模型不可用、适配层判定不该发、请求前就超时。
+	 * `aborted` 指发出前取消。`detail` 是可选的一句人读诊断（宿主原始报错等）。
+	 */
+	| { status: "not-run"; cause: "host-refused" | "unavailable" | "timeout" | "aborted"; detail?: string };
+
+/** 描述符的 `incomplete` 收的那一半：除 `completed` 之外的一切。 */
+export type IncompleteOutcome = Exclude<HeadlessOutcome, { status: "completed" }>;
+
+/** 跑一轮受限工具的 headless 会话的请求：core 构造，适配层执行。 */
 export interface HeadlessRunRequest {
 	/** prompt 全文，由 core 的 `orchestration/prompts.ts` 生成。 */
 	task: string;
@@ -52,7 +71,13 @@ export interface HeadlessRunRequest {
 }
 
 export interface HeadlessAgentPort {
-	run(req: HeadlessRunRequest): Promise<string | null>;
+	/**
+	 * 跑一轮受限工具的 headless 会话。
+	 *
+	 * 结果必须是 `HeadlessOutcome`：调用方要靠 `status` 区分「跑了但没写出东西」与「根本没跑」
+	 * （extract 描述符靠它决定要不要报 `{ skipped: true }`）。传输级异常仍可抛。
+	 */
+	run(req: HeadlessRunRequest): Promise<HeadlessOutcome>;
 }
 
 /**

package/src/orchestration/status.ts

@@ -0,0 +1,37 @@
+import { taskModel } from "../config.js";
+import type { MemoryConfig, ModelTask } from "../config.js";
+
+/**
+ * 一行模块状态：core 只给**数据**，不给文案。怎么措辞、按什么顺序展示，是适配层的事。
+ */
+export interface ModuleStatusRow {
+	id: ModelTask;
+	/** 适配层是否声明实现了该任务（`tasks` 参数里有没有它）。 */
+	implemented: boolean;
+	/** 该任务是否可用：`dream` 无包级开关恒 `true`，其余取各自的 `enabled`。 */
+	enabled: boolean;
+	/** 生效模型值（per-task 优先，其次 defaults.model）；仅当 `enabled && implemented` 时给出。 */
+	model?: string;
+}
+
+/** 顺序恒为 dream → extractMemories → autoSurfacing（与 `requiredModels` 同一口径）。 */
+const ORDER: readonly ModelTask[] = ["dream", "extractMemories", "autoSurfacing"];
+
+/**
+ * 每个任务的模块状态行数据。适配层声明自己实现了哪些任务（`tasks`），core 补上
+ * `implemented` / `enabled` / `model` 三样事实；展示顺序与措辞仍是适配层自己的事。
+ */
+export function moduleStatusRows(cfg: MemoryConfig, tasks: readonly ModelTask[]): ModuleStatusRow[] {
+	return ORDER.map((id) => {
+		const implemented = tasks.includes(id);
+		// dream 没有包级开关：恒启用。其余取各自的 `enabled`（`deepMerge` 可能把用户写的
+		// `null` 子树原样带进来，`?.` 让那类配置按「关闭」读，而不是抛 TypeError）。
+		const enabled = id === "dream" ? true : cfg[id]?.enabled === true;
+		const row: ModuleStatusRow = { id, implemented, enabled };
+		if (enabled && implemented) {
+			const model = taskModel(cfg, id);
+			if (model !== undefined) row.model = model;
+		}
+		return row;
+	});
+}

package/src/orchestration/surfacing.ts

@@ -1,22 +1,25 @@
-import type { SessionPersistenceConfig } from "../config.js";
 import type { EntryManifest } from "../injection.js";
-import { buildSideQueryTask } from "../injection.js";
-import type { HeadlessAgentPort } from "./ports.js";
+import { buildSideQueryTask, renderSurfacedEntries } from "../injection.js";
+import type { MemoryTask } from "./task.js";
 
-export interface RunSideQueryOpts {
+export interface SurfacingInput {
 	/** 本轮的候选清单（`scanEntries` 的产出）。 */
 	manifest: EntryManifest[];
 	/** 用户这一轮的输入（调用方负责先截到预算内）。 */
 	userPrompt: string;
 	/** 本 session 已经注入过的文件，不再重复选。 */
 	injectedFiles: Set<string>;
-	maxFiles: number;
-	/** 宿主的思考/推理档位，core 原样透传。 */
-	effort?: string;
-	model: string;
-	/** 子会话 cwd；传 memoryDir。 */
-	cwd: string;
-	sessionPersistence?: SessionPersistenceConfig;
+}
+
+export interface SurfacingResult {
+	/** 本轮真正渲染成功的文件；渲染不出内容时恒为 `[]`（不标记已注入）。 */
+	files: string[];
+	content: string;
+}
+
+/** 去掉已注入的文件，得到真正进入侧查询的候选清单。 */
+function candidates(input: SurfacingInput): EntryManifest[] {
+	return input.manifest.filter((entry) => !input.injectedFiles.has(entry.file));
 }
 
 /** 从侧查询的回复里解析 `selected_files`，只保留确实在候选清单里的文件。 */
@@ -32,37 +35,34 @@ function parseSelectedFiles(result: string, candidates: EntryManifest[], maxFile
 	}
 }
 
-/**
- * 跑一轮轻量侧查询，选出与用户输入相关的 entry 文件名。
- *
- * 超时/失败一律返回 `[]`，**没有回退**：auto-surfacing 是纯增益，选不出来就不注入，
- * 绝不因为侧查询挂了而打断用户这一轮。
- *
- * 返回的是**文件名**，不是注入内容 —— 「注入到哪个通道、本 session 已注入过哪些」是适配层的事。
- */
-export async function runSideQuery(
-	opts: RunSideQueryOpts,
-	ports: { headless: HeadlessAgentPort },
-): Promise<string[]> {
-	const candidates = opts.manifest.filter((entry) => !opts.injectedFiles.has(entry.file));
-	if (candidates.length === 0) return [];
-	const task = buildSideQueryTask(candidates, opts.userPrompt, opts.maxFiles);
-	try {
-		const result = await ports.headless.run({
-			task,
-			cwd: opts.cwd,
-			model: opts.model,
-			effort: opts.effort,
-			maxTurns: 1,
-			timeoutMs: 30_000,
-			// 零工具就是意图：侧查询只需要回一个 JSON，给它任何工具都是白烧 token。
-			builtinTools: "none",
-			memoryTool: null,
-			sessionPersistence: opts.sessionPersistence,
-		});
-		if (result === null) return [];
-		return parseSelectedFiles(result, candidates, opts.maxFiles);
-	} catch {
-		return [];
-	}
-}
+/** autoSurfacing 描述符：core 自读 `cfg.autoSurfacing` 的预算，适配层只给宿主数据。 */
+export const autoSurfacing: MemoryTask<SurfacingInput, SurfacingResult> = {
+	id: "autoSurfacing",
+	plan: {
+		maxTurns: 1,
+		timeoutMs: 30_000,
+		memoryTool: null,
+		lock: "none",
+		errorPolicy: "swallow",
+	},
+	buildPrompt(cfg, _deps, input) {
+		const remaining = candidates(input);
+		if (remaining.length === 0) return null;
+		return buildSideQueryTask(remaining, input.userPrompt, cfg.autoSurfacing.maxFiles);
+	},
+	async parse(cfg, deps, input, text) {
+		const selected = parseSelectedFiles(text, candidates(input), cfg.autoSurfacing.maxFiles);
+		// 只返回真正渲染出来的文件：预算被 maxInjectionBytes 截断、或 readEntry 读不到时，
+		// 未渲染的文件不能进 `files`，否则适配层会把它们标记成已注入、整个 session 不再浮现。
+		return renderSurfacedEntries(
+			deps.store,
+			selected,
+			cfg.autoSurfacing.maxEntryBytes,
+			cfg.autoSurfacing.maxInjectionBytes,
+		);
+	},
+	notCompleted() {
+		return { files: [], content: "" };
+	},
+};
+