@tachu/extensions 1.0.0-beta.1 → 1.0.0-rc.1

package/dist/memory/fs-memory-system.d.ts

@@ -0,0 +1,288 @@
+import { InMemoryMemorySystem, type AdapterCallContext, type ContextWindow, type MemoryEntry, type MemorySystem } from "@tachu/core";
+import { ProjectionOutbox } from "./projection-outbox";
+import { ProjectionWorker } from "./projection-worker";
+/**
+ * `FsMemorySystem` 构造依赖（来自 `@tachu/core` 的 `MemorySystemFactoryDeps`）。
+ *
+ * 解耦设计：extensions 不强依赖 core 的 `MemorySystemFactoryDeps` 类型签名变动，
+ * 内部自描述只取真正需要的字段。
+ */
+export interface FsMemorySystemOptions {
+    /**
+    * 持久化根目录，每个 session 对应 `<persistDir>/<sanitizedId>.jsonl`。
+    */
+    persistDir: string;
+    /**
+    * 内部组合的 `InMemoryMemorySystem` 实例。由调用方（通常为 engine-factory
+    * 通过 core 的 factory 回调）构造好后传入，以复用 core 的 tokenizer /
+    * modelRouter / providers / vectorStore 等运行时依赖。
+    */
+    inner: InMemoryMemorySystem;
+    /**
+    * 压缩触发阈值（0-1）。默认读 `config.memory.compressionThreshold`。
+    * 超过 `contextTokenLimit * threshold` 时在 `append` 中触发 `compress`。
+    */
+    compressionThreshold: number;
+    /**
+    * 可选的 projection outbox。若提供，`archive()` 会通过 outbox
+    * 跟踪每条投递的状态（pending/retrying/indexed/failed/dead），`pendingProjection`
+    * 返回真实状态而非常量模板；启动时自动 `recover()` 陈旧 retrying 项。
+    * 不提供时退化到旧的"始终 pending"行为，保持向后兼容。
+    */
+    projectionOutbox?: ProjectionOutbox | undefined;
+    /**
+    * optional embed+vector projection callback for {@link ProjectionWorker}.
+    * When set, {@link createProjectionWorker} uses this instead of `inner.project`.
+    */
+    projectionProject?: (sessionId: string, refs: readonly string[], signal: AbortSignal) => Promise<import("./projection-worker").ProjectionWorkerProjectResult[] | void>;
+}
+export interface FsArchiveOptions {
+    awaitProjection?: boolean | undefined;
+}
+/**
+ * 将任意 session ID 标准化为文件名安全形式。
+ *
+ * 规则：
+ * - 仅保留 `[A-Za-z0-9._-]`，其余一律替换为 `_`
+ * - 首位不允许为 `.`（防止写隐藏文件 / 触发 shell 点号展开）
+ * - 空串兜底为 `default`
+ * - 超长截断到 120 字符（绝大多数 UUID / nanoid 场景足够）
+ */
+export declare function sanitizeSessionId(raw: string): string;
+/**
+ * 基于文件系统的 `MemorySystem` 实现 —— `@tachu/core` `MemorySystem` 抽象的
+ * **跨进程持久化** 参考实现（patch-02-session-persistence）。
+ *
+ * ## 职责
+ *
+ * - 每次 `append` 先把单条 entry 以 append-only JSON line 写入
+ * `<persistDir>/<sid>.jsonl`（crash-safe），再同步进内部
+ * `InMemoryMemorySystem` 的运行时 window
+ * - 首次 `load(sid)` 命中时从磁盘 hydrate 上次进程遗留的历史，注入内部
+ * `InMemoryMemorySystem`（走 public `hydrate()`，旁路 per-entry compress 触发）
+ * - `compress()` 完成后 atomic rewrite 持久化文件，保证"盘 = 内存"一致
+ * - `recall` / `archive` / `getSize` / `trim` 全部代理内部 `InMemoryMemorySystem`
+ * （只要 load 阶段已 hydrate，这些读路径天然拿到跨进程数据）
+ *
+ * ## 并发
+ *
+ * 单 session 上的 `load` / `append` / `compress` / `trim` 通过 per-session promise
+ * chain 串行化，避免两个 runStream 并发交错写出错乱 jsonl。跨 session 完全独立。
+ *
+ * ## 与 `archivePath` 的职责分离
+ *
+ * - `config.memory.persistDir`（本类）= 热路径：每次 append 即落盘，用于跨进程 `--resume`
+ * - `config.memory.archivePath`（内部 `InMemoryMemorySystem` 拥有）= 冷路径：
+ * 仅在 `compress()` 时一次性追加到单个大 jsonl，供长期记忆向量召回
+ *
+ * 两者**不重叠**，保留现有 archivePath 语义不动。
+ */
+export type FsProjectionStatus = {
+    kind: "pending";
+    ref: string;
+    reason: string;
+    createdAt: number;
+} | {
+    kind: "indexed";
+    ref: string;
+    indexedAt: number;
+    adapter: string;
+} | {
+    kind: "failed";
+    ref: string;
+    error: string;
+    retryable: boolean;
+    attempts: number;
+} | {
+    kind: "stale";
+    ref: string;
+    reason: string;
+};
+export interface FsMemorySummary {
+    id: string;
+    sessionId: string;
+    sourceEntryIds: string[];
+    sourceRange: {
+        fromTs: number;
+        toTs: number;
+    };
+    content: string;
+    method: "llm" | "head-middle-tail" | "manual";
+    model?: string | undefined;
+    createdAt: number;
+}
+export interface FsSessionCheckpoint {
+    id: string;
+    createdAt: number;
+    state?: unknown | undefined;
+}
+export interface FsSessionMemorySnapshot {
+    meta: {
+        id: string;
+        updatedAt: number;
+        entryCount: number;
+    };
+    hotLog: MemoryEntry[];
+    summaries: FsMemorySummary[];
+    archiveRefs: Array<{
+        id: string;
+        path?: string | undefined;
+        entryIds: string[];
+        createdAt: number;
+    }>;
+    projectionStatus: FsProjectionStatus[];
+    budget: {
+        tokenLimit?: number | undefined;
+        tokenUsed?: number | undefined;
+    };
+    checkpoint?: FsSessionCheckpoint | undefined;
+}
+export interface FsMemoryViewRequest {
+    kind: "hot-log" | "summary" | "export" | "recall-corpus" | "sub-agent-slice";
+    limit?: number | undefined;
+    since?: number | undefined;
+    includeArchived?: boolean | undefined;
+}
+export interface FsMemoryView {
+    kind: FsMemoryViewRequest["kind"];
+    entries: MemoryEntry[];
+    summaries: FsMemorySummary[];
+    projectionStatus: FsProjectionStatus[];
+}
+export declare class FsMemorySystem implements MemorySystem {
+    private readonly persistDir;
+    private readonly inner;
+    private readonly compressionThreshold;
+    private readonly hydrated;
+    private readonly pending;
+    private readonly checkpoints;
+    private readonly outbox?;
+    private readonly projectionProject?;
+    private readonly recovered;
+    /**
+    * 构造文件持久化 MemorySystem。
+    *
+    * @param options 参见 {@link FsMemorySystemOptions}
+    */
+    constructor(options: FsMemorySystemOptions);
+    /**
+    * @inheritdoc
+    */
+    load(sessionId: string, ctx: AdapterCallContext): Promise<ContextWindow>;
+    /**
+    * @inheritdoc
+    *
+    * 流程：
+    * 1. 确保 session 已 hydrate（使 window 与磁盘一致）
+    * 2. append-only 将 entry 序列化为单行 JSON 落盘（崩溃安全；即便本次进程 crash，
+    * 磁盘文件仍是合法 jsonl 的前缀）
+    * 3. 将 entry 通过 `inner.hydrate()` 注入内存 window（旁路 per-entry compress）
+    * 4. 手动检查 tokenCount 是否越过阈值；若越线：
+    * - `inner.compress(sid)` 触发 LLM 摘要
+    * - atomic rewrite jsonl，保持盘与内存一致
+    */
+    append(sessionId: string, entry: MemoryEntry, ctx: AdapterCallContext): Promise<void>;
+    appendEntries(sessionId: string, entries: MemoryEntry[], ctx: AdapterCallContext): Promise<{
+        appended: number;
+        projectionStatus: FsProjectionStatus[];
+    }>;
+    /**
+    * @inheritdoc
+    */
+    compress(sessionId: string): Promise<void>;
+    /**
+    * @inheritdoc
+    */
+    recall(sessionId: string, query: string, topK?: number): Promise<MemoryEntry[]>;
+    /**
+    * @inheritdoc
+    */
+    loadFull(sessionId: string): Promise<MemoryEntry[]>;
+    loadSession(sessionId: string, ctx: AdapterCallContext): Promise<FsSessionMemorySnapshot>;
+    loadView(sessionId: string, view: FsMemoryViewRequest, ctx: AdapterCallContext): Promise<FsMemoryView>;
+    compact(sessionId: string, _policy: {
+        targetTokens?: number;
+        method?: "llm" | "head-middle-tail" | "manual";
+    }, _ctx: AdapterCallContext): Promise<{
+        summaries: FsMemorySummary[];
+        archiveRefs: FsSessionMemorySnapshot["archiveRefs"];
+    }>;
+    checkpoint(sessionId: string, checkpoint: FsSessionCheckpoint, _ctx: AdapterCallContext): Promise<void>;
+    /**
+    * @inheritdoc
+    *
+    * 当 host 注入 `projectionOutbox` 时，每条 entry 走 outbox 状态机
+    * （pending → retrying → indexed/failed/dead），并在首次 archive 该 session 时
+    * 自动 `recover()` 残留的陈旧 retrying 项。
+    *
+    * `awaitProjection=false` 时只写冷归档并入队 projection，由 `ProjectionWorker`
+    * 后台 flush；默认保持旧同步语义，等待本轮 projection 完成后返回。
+    */
+    archive(sessionId: string, options?: FsArchiveOptions): Promise<void>;
+    /**
+    * Construct a {@link ProjectionWorker} that drains the outbox via the
+    * host-injected `projectionProject` callback.
+    *
+    * **Fail-closed contract:** when `projectionOutbox` is
+    * enabled, `projectionProject` MUST be provided. The legacy fallback to
+    * `InMemoryMemorySystem.project()` (which forwarded raw `string` content
+    * straight to `VectorStore.upsert(id, text, { content })` and bypassed the
+    * `EmbeddingRuntime` / `VectorIndexAdapter` stack) has been removed — any
+    * production host that forgets to wire the projector now crashes loudly
+    * instead of silently re-introducing the deprecated text-embed path.
+    */
+    createProjectionWorker(options?: {
+        intervalMs?: number | undefined;
+    }): ProjectionWorker;
+    /**
+    * @inheritdoc
+    */
+    getSize(sessionId: string): Promise<{
+        entries: number;
+        tokens: number;
+    }>;
+    /**
+    * @inheritdoc
+    */
+    trim(sessionId: string, options?: {
+        keepHead?: number;
+        keepTail?: number;
+    }): Promise<void>;
+    /**
+    * @inheritdoc
+    *
+    * 先清内存 window，再幂等删除磁盘 jsonl。未找到文件视为 no-op。
+    */
+    clear(sessionId: string): Promise<void>;
+    private pendingProjection;
+    private snapshotOutboxByRef;
+    private projectionStatusFor;
+    /** archiveRefs 持久化路径。 */
+    private archiveRefsPathFor;
+    private readArchiveRefs;
+    private writeArchiveRefs;
+    private extractSummaries;
+    /**
+    * 获取某 session 的持久化文件绝对 / 相对路径（便于外层 CLI 做迁移、/history 展示）。
+    */
+    pathFor(sessionId: string): string;
+    /**
+    * 从磁盘读取 session 的原始 entries 快照（不经 inner hydrate）。
+    *
+    * 外层 CLI 可借此在 `/history` / `/export` 命令中直接列出原始条目顺序，
+    * 不必先 `load` 触发 hydrate 副作用。
+    */
+    readRaw(sessionId: string): Promise<MemoryEntry[]>;
+    private parseJsonl;
+    private hydrateIfNeeded;
+    private writeJsonlLine;
+    private rewriteJsonl;
+    /**
+    * 串行化某 session 的关键操作 —— 通过 promise chain 保证同一 sessionId 上的
+    * load / append / compress / trim 不交错。
+    *
+    * 失败不阻塞队列：下一个 task 无论前一个 resolve 还是 reject 都会启动。
+    */
+    private serialize;
+}
+//# sourceMappingURL=fs-memory-system.d.ts.map

package/dist/memory/fs-memory-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-memory-system.d.ts","sourceRoot":"","sources":["../../src/memory/fs-memory-system.ts"],"names":[],"mappings":"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"}