hyacinth-ai 0.9.6

package/dist/mcp/process-transport.d.ts

@@ -0,0 +1,21 @@
+import type { ChildProcess } from 'node:child_process';
+import type { Transport, TransportSendOptions } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { JSONRPCMessage, MessageExtraInfo } from '@modelcontextprotocol/sdk/types.js';
+export declare class ProcessTransport implements Transport {
+    private proc;
+    private readBuffer;
+    private onDataHandler;
+    private onCloseHandler;
+    private onErrorHandler;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: <T extends JSONRPCMessage>(message: T, extra?: MessageExtraInfo) => void;
+    sessionId?: string;
+    setProtocolVersion?: (version: string) => void;
+    constructor(proc: ChildProcess);
+    start(): Promise<void>;
+    send(message: JSONRPCMessage, options?: TransportSendOptions): Promise<void>;
+    close(): Promise<void>;
+    private processReadBuffer;
+}
+//# sourceMappingURL=process-transport.d.ts.map

package/dist/mcp/process-transport.js

@@ -0,0 +1,59 @@
+import { ReadBuffer, serializeMessage } from '@modelcontextprotocol/sdk/shared/stdio.js';
+export class ProcessTransport {
+    proc;
+    readBuffer = new ReadBuffer();
+    onDataHandler;
+    onCloseHandler;
+    onErrorHandler;
+    onclose;
+    onerror;
+    onmessage;
+    sessionId;
+    setProtocolVersion;
+    constructor(proc) {
+        this.proc = proc;
+        this.onDataHandler = (chunk) => {
+            this.readBuffer.append(chunk);
+            this.processReadBuffer();
+        };
+        this.onCloseHandler = () => {
+            this.onclose?.();
+        };
+        this.onErrorHandler = (err) => {
+            this.onerror?.(err);
+        };
+    }
+    async start() {
+        if (!this.proc.stdout) {
+            throw new Error('Process stdout is not available');
+        }
+        this.proc.stdout.on('data', this.onDataHandler);
+        this.proc.on('close', this.onCloseHandler);
+        this.proc.on('error', this.onErrorHandler);
+    }
+    async send(message, options) {
+        if (!this.proc.stdin || this.proc.stdin.destroyed) {
+            throw new Error('Process stdin is not available');
+        }
+        const line = serializeMessage(message);
+        this.proc.stdin.write(line);
+    }
+    async close() {
+        this.proc.stdout?.off('data', this.onDataHandler);
+        this.proc.off('close', this.onCloseHandler);
+        this.proc.off('error', this.onErrorHandler);
+        this.readBuffer.clear();
+        this.onclose?.();
+    }
+    processReadBuffer() {
+        while (true) {
+            const message = this.readBuffer.readMessage();
+            if (message === null)
+                break;
+            if (this.onmessage) {
+                this.onmessage(message);
+            }
+        }
+    }
+}
+//# sourceMappingURL=process-transport.js.map

package/dist/mcp/side-effect.d.ts

@@ -0,0 +1,5 @@
+/** Sanitize MCP name: replace non-alphanumeric chars (except - and _) with - */
+export declare function sanitizeMcpName(name: string): string;
+/** 判断 MCP 工具名是否暗示副作用（用于工具描述中标记 [side-effect]） */
+export declare function hasSideEffect(toolName: string): boolean;
+//# sourceMappingURL=side-effect.d.ts.map

package/dist/mcp/side-effect.js

@@ -0,0 +1,21 @@
+/** Sanitize MCP name: replace non-alphanumeric chars (except - and _) with - */
+export function sanitizeMcpName(name) {
+    return name.replace(/[^a-zA-Z0-9_-]/g, '-').replace(/-+/g, '-');
+}
+/** MCP 工具名中暗示副作用的操作关键词（如 create、delete、write 等） */
+const SIDE_EFFECT_KEYWORDS = new Set([
+    'navigate', 'create', 'delete', 'open', 'write', 'execute',
+    'run', 'start', 'launch', 'install', 'remove', 'update',
+    'send', 'post', 'put', 'patch',
+]);
+/** 判断 MCP 工具名是否暗示副作用（用于工具描述中标记 [side-effect]） */
+export function hasSideEffect(toolName) {
+    const lower = toolName.toLowerCase();
+    for (const keyword of SIDE_EFFECT_KEYWORDS) {
+        if (lower === keyword || lower.startsWith(keyword) || lower.includes(keyword)) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=side-effect.js.map

package/dist/mcp/system.d.ts

@@ -0,0 +1,95 @@
+import { MCPServerManager } from './lifecycle.js';
+import { MCPBridge } from './bridge.js';
+import type { ToolRegistry } from '../tools/registry.js';
+import type { LayeredContextComposer } from '../context/composer.js';
+import type { LifecycleSupervisor } from '../lifecycle/supervisor.js';
+import type { MCPConfig } from '../types.js';
+import { createLogger } from '../logging/logger.js';
+export interface MCPStatusEvent {
+    type: 'added' | 'removed' | 'failed';
+    name: string;
+    tools?: string[];
+}
+export interface MCPSystemDeps {
+    cwd: string;
+    logger?: ReturnType<typeof createLogger>;
+}
+interface MCPServerStatus {
+    name: string;
+    connected: boolean;
+}
+/**
+ * MCPSystem — MCP 模块统一管理器
+ *
+ * 对标 PluginManager 的管理模式，封装 MCP 的完整生命周期：
+ *   - start(): 加载配置 → 连接所有 MCP Server → 注册工具/ContextSource/Supervisor
+ *   - stop(): 断开所有 MCP Server
+ *   - reload(): 热加载，增量增/删/改 MCP Server
+ *
+ * 所有 MCP Server 随主进程启动而启动，随主进程关闭而关闭。
+ */
+export declare class MCPSystem {
+    private managers;
+    private installManager;
+    private bridge;
+    private configLoader;
+    private currentConfigs;
+    private cwd;
+    private logger;
+    private statusCallback?;
+    private toolRegistry?;
+    private contextComposer?;
+    private supervisor?;
+    constructor(deps: MCPSystemDeps);
+    /** 启动所有 MCP Server */
+    start(): Promise<void>;
+    /** 停止所有 MCP Server */
+    stop(): Promise<void>;
+    /** 热加载重载 */
+    reload(): Promise<void>;
+    /** 注册到 ToolRegistry */
+    registerToToolRegistry(registry: ToolRegistry): void;
+    /** 注册到 ContextComposer — 每个 Server 注册为独立 ContextSource */
+    registerToContextComposer(composer: LayeredContextComposer): void;
+    /** 注册到 LifecycleSupervisor */
+    registerToLifecycleSupervisor(supervisor: LifecycleSupervisor): void;
+    /** 获取 MCPBridge 实例 */
+    getBridge(): MCPBridge;
+    /** 获取所有 Manager */
+    getManagers(): MCPServerManager[];
+    /** 获取所有 MCP Server 状态 */
+    getStatus(): MCPServerStatus[];
+    /** 注册状态变更回调 */
+    onStatusChange(cb: (event: MCPStatusEvent) => void): void;
+    /** 触发状态变更事件 */
+    private emitStatus;
+    /**
+     * 添加外部来源的 MCP Server（如插件注册）。
+     * 与 mcp.json 配置的 Server 统一走 addServer 路径，享受相同的生命周期管理、热插拔缓存策略和优雅关闭保护。
+     */
+    addExternalServer(config: MCPConfig, opts?: {
+        isHotPlug?: boolean;
+    }): Promise<void>;
+    /**
+     * 批量添加外部 MCP Server 配置。用于 PluginManager 统一注册插件声明的 MCP。
+     */
+    addExternalServers(configs: MCPConfig[], opts?: {
+        isHotPlug?: boolean;
+    }): Promise<void>;
+    /**
+     * 按名称移除 Server（外部调用）。PluginManager 在 deactivate 插件时使用。
+     */
+    removeExternalServer(name: string): Promise<void>;
+    /** 添加单个 MCP Server。isHotPlug=true 时 ContextSource 使用 live 缓存策略（进 Zone 5），避免破坏 Zone 2-3 前缀缓存。 */
+    private addServer;
+    /** 移除单个 MCP Server */
+    private removeServer;
+    /** 同步 MCPBridge 的 clients/managers 列表 */
+    private syncBridge;
+    /** 同步所有 ContextSource */
+    private syncContextSources;
+    /** 注册单个 Server 的 ContextSource。isHotPlug 时用 live 策略（进 Zone 5 临时区），否则用 manifest 策略（进 Zone 2 稳定前缀）。 */
+    private registerServerContextSource;
+}
+export {};
+//# sourceMappingURL=system.d.ts.map

package/dist/mcp/system.js

@@ -0,0 +1,279 @@
+import { MCPConfigLoader } from './config.js';
+import { MCPServerManager } from './lifecycle.js';
+import { MCPBridge } from './bridge.js';
+import { MCPInstallManager } from './install-manager.js';
+import { createLogger } from '../logging/logger.js';
+/**
+ * MCPSystem — MCP 模块统一管理器
+ *
+ * 对标 PluginManager 的管理模式，封装 MCP 的完整生命周期：
+ *   - start(): 加载配置 → 连接所有 MCP Server → 注册工具/ContextSource/Supervisor
+ *   - stop(): 断开所有 MCP Server
+ *   - reload(): 热加载，增量增/删/改 MCP Server
+ *
+ * 所有 MCP Server 随主进程启动而启动，随主进程关闭而关闭。
+ */
+export class MCPSystem {
+    managers = [];
+    installManager;
+    bridge;
+    configLoader;
+    currentConfigs = [];
+    cwd;
+    logger;
+    statusCallback;
+    // 外部依赖（通过 register 方法注入）
+    toolRegistry;
+    contextComposer;
+    supervisor;
+    constructor(deps) {
+        this.cwd = deps.cwd;
+        this.logger = deps.logger ?? createLogger('mcp:system');
+        this.configLoader = new MCPConfigLoader();
+        this.installManager = new MCPInstallManager();
+        this.bridge = new MCPBridge([]);
+    }
+    /** 启动所有 MCP Server */
+    async start() {
+        this.currentConfigs = await this.configLoader.load(this.cwd);
+        for (const config of this.currentConfigs) {
+            await this.addServer(config);
+        }
+        this.logger.info(`MCPSystem started: ${this.managers.length}/${this.currentConfigs.length} servers connected`);
+    }
+    /** 停止所有 MCP Server */
+    async stop() {
+        for (const manager of this.managers) {
+            try {
+                await manager.disconnect();
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                this.logger.warn(`disconnect error for ${manager.getName()}: ${msg}`);
+            }
+        }
+        this.managers = [];
+        this.bridge.updateClients([], []);
+        this.currentConfigs = [];
+        this.logger.info('MCPSystem stopped');
+    }
+    /** 热加载重载 */
+    async reload() {
+        const newConfigs = await this.configLoader.load(this.cwd);
+        const oldMap = new Map(this.currentConfigs.map(c => [c.name, c]));
+        const newMap = new Map(newConfigs.map(c => [c.name, c]));
+        // Added — 热插拔：新增 Server 标记 isHotPlug，ContextSource 进 Zone 5 临时区
+        for (const [name, cfg] of newMap) {
+            if (!oldMap.has(name)) {
+                this.logger.info('MCP server added (hot-plug)', { name });
+                await this.addServer(cfg, { isHotPlug: true });
+            }
+        }
+        // Removed
+        for (const [name] of oldMap) {
+            if (!newMap.has(name)) {
+                this.logger.info('MCP server removed', { name });
+                await this.removeServer(name);
+            }
+        }
+        // Changed — 热插拔：先 remove 再 add，新实例也标记 isHotPlug
+        for (const [name, newCfg] of newMap) {
+            const oldCfg = oldMap.get(name);
+            if (oldCfg && !configsEqual(oldCfg, newCfg)) {
+                this.logger.info('MCP server changed (hot-plug)', { name });
+                await this.removeServer(name);
+                await this.addServer(newCfg, { isHotPlug: true });
+            }
+        }
+        this.currentConfigs = newConfigs;
+        this.logger.info(`MCPSystem reloaded: ${this.managers.length} servers`);
+    }
+    /** 注册到 ToolRegistry */
+    registerToToolRegistry(registry) {
+        this.toolRegistry = registry;
+        this.bridge.registerToRegistry(registry);
+    }
+    /** 注册到 ContextComposer — 每个 Server 注册为独立 ContextSource */
+    registerToContextComposer(composer) {
+        this.contextComposer = composer;
+        this.syncContextSources(composer);
+    }
+    /** 注册到 LifecycleSupervisor */
+    registerToLifecycleSupervisor(supervisor) {
+        this.supervisor = supervisor;
+        for (const manager of this.managers) {
+            supervisor.registerMCPServer(manager.getProcessManager());
+        }
+    }
+    /** 获取 MCPBridge 实例 */
+    getBridge() {
+        return this.bridge;
+    }
+    /** 获取所有 Manager */
+    getManagers() {
+        return this.managers;
+    }
+    /** 获取所有 MCP Server 状态 */
+    getStatus() {
+        return this.managers.map(m => ({
+            name: m.getName(),
+            connected: m.isConnected(),
+        }));
+    }
+    /** 注册状态变更回调 */
+    onStatusChange(cb) {
+        this.statusCallback = cb;
+    }
+    /** 触发状态变更事件 */
+    emitStatus(event) {
+        this.statusCallback?.(event);
+        this.logger.info(`MCP status: ${event.type}`, { name: event.name, tools: event.tools?.join(',') });
+    }
+    /**
+     * 添加外部来源的 MCP Server（如插件注册）。
+     * 与 mcp.json 配置的 Server 统一走 addServer 路径，享受相同的生命周期管理、热插拔缓存策略和优雅关闭保护。
+     */
+    async addExternalServer(config, opts) {
+        await this.addServer(config, opts);
+    }
+    /**
+     * 批量添加外部 MCP Server 配置。用于 PluginManager 统一注册插件声明的 MCP。
+     */
+    async addExternalServers(configs, opts) {
+        for (const config of configs) {
+            await this.addServer(config, opts);
+        }
+    }
+    /**
+     * 按名称移除 Server（外部调用）。PluginManager 在 deactivate 插件时使用。
+     */
+    async removeExternalServer(name) {
+        await this.removeServer(name);
+    }
+    // ── 内部方法 ──
+    /** 添加单个 MCP Server。isHotPlug=true 时 ContextSource 使用 live 缓存策略（进 Zone 5），避免破坏 Zone 2-3 前缀缓存。 */
+    async addServer(config, opts = {}) {
+        const isHotPlug = opts.isHotPlug ?? false;
+        // 安装管理：确保包已安装，更新 command/args
+        const resolved = await this.installManager.ensureInstalled(config);
+        if (resolved === null && config.packageType) {
+            this.logger.warn(`MCP server "${config.name}" install failed, skipping`);
+            return;
+        }
+        const effectiveConfig = resolved ? { ...config, command: resolved.command, args: resolved.args } : config;
+        const manager = new MCPServerManager(effectiveConfig);
+        const ok = await manager.connect();
+        if (!ok) {
+            this.logger.warn(`MCP server "${config.name}" connect failed, skipping`);
+            // 连接失败时清理子进程
+            try {
+                await manager.disconnect();
+            }
+            catch {
+                // 忽略断开连接时的错误
+            }
+            this.emitStatus({ type: 'failed', name: config.name });
+            return;
+        }
+        this.managers.push(manager);
+        this.syncBridge();
+        // 注册到 ToolRegistry
+        if (this.toolRegistry) {
+            this.bridge.registerToRegistry(this.toolRegistry);
+        }
+        // 注册到 ContextComposer — 热插拔与持久化使用不同 cacheability
+        if (this.contextComposer) {
+            this.registerServerContextSource(config.name, manager, this.contextComposer, isHotPlug);
+        }
+        // 注册到 LifecycleSupervisor
+        if (this.supervisor) {
+            this.supervisor.registerMCPServer(manager.getProcessManager());
+        }
+        this.emitStatus({ type: 'added', name: config.name, tools: manager.getClient().getTools().map(t => t.name) });
+    }
+    /** 移除单个 MCP Server */
+    async removeServer(name) {
+        const idx = this.managers.findIndex(m => m.getName() === name);
+        if (idx === -1)
+            return;
+        const manager = this.managers[idx];
+        const oldToolNames = manager.getClient().getTools().map(t => t.name);
+        // 注销工具
+        if (this.toolRegistry) {
+            this.bridge.unregisterTools(name, this.toolRegistry);
+        }
+        // 注销 ContextSource
+        if (this.contextComposer) {
+            this.contextComposer.unregisterSource(`mcp-${name}`);
+        }
+        // 断开连接
+        try {
+            await manager.disconnect();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.logger.warn(`disconnect error for ${name}: ${msg}`);
+        }
+        this.managers.splice(idx, 1);
+        this.syncBridge();
+        this.emitStatus({ type: 'removed', name, tools: oldToolNames });
+    }
+    /** 同步 MCPBridge 的 clients/managers 列表 */
+    syncBridge() {
+        const clients = this.managers.map(m => m.getClient());
+        this.bridge.updateClients(clients, this.managers);
+    }
+    /** 同步所有 ContextSource */
+    syncContextSources(composer) {
+        for (const manager of this.managers) {
+            this.registerServerContextSource(manager.getName(), manager, composer);
+        }
+    }
+    /** 注册单个 Server 的 ContextSource。isHotPlug 时用 live 策略（进 Zone 5 临时区），否则用 manifest 策略（进 Zone 2 稳定前缀）。 */
+    registerServerContextSource(name, manager, composer, isHotPlug = false) {
+        const client = manager.getClient();
+        composer.registerSource({
+            name: `mcp-${name}`,
+            strategy: 'index_only',
+            cacheability: isHotPlug ? 'live' : 'manifest',
+            description: name,
+            getContent: () => client.getToolIndex(),
+        });
+    }
+}
+// ── 比较两个 MCPConfig 是否相等 ──
+function configsEqual(a, b) {
+    return (a.command === b.command &&
+        arrayEqualUnordered(a.args, b.args) &&
+        a.url === b.url &&
+        objectEqual(a.env, b.env) &&
+        objectEqual(a.headers, b.headers) &&
+        a.packageType === b.packageType &&
+        a.package === b.package &&
+        a.packageVersion === b.packageVersion &&
+        a.connectTimeout === b.connectTimeout &&
+        a.callTimeout === b.callTimeout);
+}
+function arrayEqualUnordered(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    if (a.length !== b.length)
+        return false;
+    const sortedA = [...a].sort();
+    const sortedB = [...b].sort();
+    return sortedA.every((v, i) => v === sortedB[i]);
+}
+function objectEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    const keysA = Object.keys(a).sort();
+    const keysB = Object.keys(b).sort();
+    if (keysA.length !== keysB.length)
+        return false;
+    return keysA.every((key, i) => key === keysB[i] && a[key] === b[key]);
+}
+//# sourceMappingURL=system.js.map

package/dist/memory/companion-session.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CompanionSessionManager — 管理陪伴模式专用 session（全局单例）。
+ *
+ * 每个角色独立目录。进入陪伴模式时根据角色名自动恢复，
+ * 重置时仅归档对话文件（conversation/events/stats），不动 world.json。
+ */
+export declare class CompanionSessionManager {
+    private dir;
+    /** 全局单例 */
+    private static instance;
+    static getInstance(): CompanionSessionManager;
+    /** 设置/切换当前角色 */
+    setCharacter(name: string): void;
+    /** 返回当前角色的陪伴目录路径（首次调用时自动创建） */
+    getOrCreate(): string;
+    /**
+     * 重置陪伴 session：仅归档对话文件，不动 world.json（世界数据跨会话保留）。
+     */
+    reset(): Promise<string>;
+    private initSessionSync;
+}
+//# sourceMappingURL=companion-session.d.ts.map

package/dist/memory/companion-session.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs/promises';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createLogger } from '../logging/logger.js';
+const logger = createLogger('companion-session');
+/**
+ * 陪伴 session 目录：~/.agent/companion/<角色名>/
+ *
+ * 按角色隔离：一个角色一个目录，内含 world.json（世界数据）+ 会话文件。
+ * 所有渠道（TUI、飞书、HTTP）共享同一份对话。
+ * 与正常 session（~/.agent/sessions/）完全分开，不受 SessionManager.cleanup() 影响。
+ */
+function getCompanionDir(name) {
+    return path.join(os.homedir(), '.agent', 'companion', name);
+}
+/**
+ * CompanionSessionManager — 管理陪伴模式专用 session（全局单例）。
+ *
+ * 每个角色独立目录。进入陪伴模式时根据角色名自动恢复，
+ * 重置时仅归档对话文件（conversation/events/stats），不动 world.json。
+ */
+export class CompanionSessionManager {
+    dir = '';
+    /** 全局单例 */
+    static instance;
+    static getInstance() {
+        if (!CompanionSessionManager.instance) {
+            CompanionSessionManager.instance = new CompanionSessionManager();
+        }
+        return CompanionSessionManager.instance;
+    }
+    /** 设置/切换当前角色 */
+    setCharacter(name) {
+        this.dir = getCompanionDir(name);
+    }
+    /** 返回当前角色的陪伴目录路径（首次调用时自动创建） */
+    getOrCreate() {
+        if (!existsSync(this.dir)) {
+            mkdirSync(this.dir, { recursive: true });
+            this.initSessionSync();
+            logger.info('Created companion session', { dir: this.dir });
+        }
+        return this.dir;
+    }
+    /**
+     * 重置陪伴 session：仅归档对话文件，不动 world.json（世界数据跨会话保留）。
+     */
+    async reset() {
+        const archiveRoot = path.join(this.dir, 'sessions-archive');
+        await fs.mkdir(archiveRoot, { recursive: true });
+        const archiveDir = path.join(archiveRoot, String(Date.now()));
+        await fs.mkdir(archiveDir, { recursive: true });
+        const sessionFiles = ['conversation.jsonl', 'events.jsonl', 'stats.json'];
+        for (const f of sessionFiles) {
+            const src = path.join(this.dir, f);
+            try {
+                await fs.rename(src, path.join(archiveDir, f));
+            }
+            catch {
+                // 文件不存在则跳过
+            }
+        }
+        logger.info('Archived conversation files', { archiveDir });
+        this.initSessionSync();
+        logger.info('Created new companion session', { dir: this.dir });
+        return this.dir;
+    }
+    initSessionSync() {
+        const now = new Date().toISOString();
+        writeFileSync(path.join(this.dir, 'meta.json'), JSON.stringify({ type: 'companion', createdAt: now }), 'utf-8');
+        writeFileSync(path.join(this.dir, 'conversation.jsonl'), '', 'utf-8');
+        writeFileSync(path.join(this.dir, 'events.jsonl'), '', 'utf-8');
+        writeFileSync(path.join(this.dir, 'stats.json'), JSON.stringify({ turns: 0, input_tokens: 0, output_tokens: 0, tool_calls: 0 }), 'utf-8');
+    }
+}
+//# sourceMappingURL=companion-session.js.map

package/dist/memory/compression-boundary.d.ts

@@ -0,0 +1,20 @@
+export interface CompressionBoundary {
+    /** 已压缩消息的数量（conversation.jsonl 中前 N 条已被摘要覆盖） */
+    compressedCount: number;
+    /** 最后一次压缩的轮次 */
+    lastCompactTurn: number;
+}
+/**
+ * 读取压缩边界信息。
+ * 文件不存在时返回默认值 { compressedCount: 0, lastCompactTurn: 0 }。
+ *
+ * @param sessionId 会话 ID
+ * @param jsonlLength conversation.jsonl 的当前消息数（用于 truncate 安全降级）
+ */
+export declare function readCompressionBoundary(sessionId: string, jsonlLength: number): Promise<CompressionBoundary>;
+/**
+ * 写入压缩边界信息。
+ * 自动创建目录。
+ */
+export declare function writeCompressionBoundary(sessionId: string, boundary: CompressionBoundary): Promise<void>;
+//# sourceMappingURL=compression-boundary.d.ts.map

package/dist/memory/compression-boundary.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+const DEFAULT_BOUNDARY = {
+    compressedCount: 0,
+    lastCompactTurn: 0,
+};
+function getBoundaryPath(sessionId) {
+    return path.join(os.homedir(), '.agent', 'sessions', sessionId, 'compression-boundary.json');
+}
+/**
+ * 读取压缩边界信息。
+ * 文件不存在时返回默认值 { compressedCount: 0, lastCompactTurn: 0 }。
+ *
+ * @param sessionId 会话 ID
+ * @param jsonlLength conversation.jsonl 的当前消息数（用于 truncate 安全降级）
+ */
+export async function readCompressionBoundary(sessionId, jsonlLength) {
+    try {
+        const content = await fs.readFile(getBoundaryPath(sessionId), 'utf-8');
+        const boundary = JSON.parse(content);
+        // truncate 安全降级：jsonl 被截断导致 compressedCount >= jsonl 长度
+        if (boundary.compressedCount >= jsonlLength) {
+            return { compressedCount: 0, lastCompactTurn: 0 };
+        }
+        return boundary;
+    }
+    catch {
+        return { ...DEFAULT_BOUNDARY };
+    }
+}
+/**
+ * 写入压缩边界信息。
+ * 自动创建目录。
+ */
+export async function writeCompressionBoundary(sessionId, boundary) {
+    await fs.mkdir(path.dirname(getBoundaryPath(sessionId)), { recursive: true });
+    await fs.writeFile(getBoundaryPath(sessionId), JSON.stringify(boundary), 'utf-8');
+}
+//# sourceMappingURL=compression-boundary.js.map

package/dist/memory/conversation.d.ts

@@ -0,0 +1,34 @@
+import type { Message } from '../types.js';
+export declare class ConversationStore {
+    private readonly maxMessages;
+    private readonly conversationFile;
+    constructor(maxMessages?: number, conversationFile?: string);
+    private getFilePath;
+    ensureFile(filePath: string): Promise<void>;
+    /**
+     * 追加消息到 conversation.jsonl
+     */
+    append(sessionDir: string, message: Message): Promise<void>;
+    /**
+     * 读取全部消息
+     */
+    readAll(sessionDir: string): Promise<Message[]>;
+    /**
+     * 读取最后 n 条消息
+     */
+    readLast(sessionDir: string, n: number): Promise<Message[]>;
+    /**
+     * 统计消息数量
+     */
+    count(sessionDir: string): Promise<number>;
+    /**
+     * 截断旧消息，保留最新的消息
+     */
+    private truncate;
+    /**
+     * 替换全部消息（用于压缩后写回）
+     * 使用 write-to-temp + rename 原子写入模式，防止写入过程中崩溃导致文件损坏
+     */
+    replace(sessionDir: string, messages: Message[]): Promise<void>;
+}
+//# sourceMappingURL=conversation.d.ts.map