@dsh-cc/memory-consolidation 0.5.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/memory/memory-consolidation/README.md
+README.md: 896afedbd85a4ab522b4466675d5f67579ca0908
+README.zh.md: 6dba1863f1923f21749191200f1eb865ad2720d1

package/README.md

@@ -0,0 +1,116 @@
+# dsh-memory-consolidation
+
+English | [中文](README.zh.md)
+
+Background memory consolidation for the DeepSeek Harness: turn-end extraction
+and the three-gate dream rewrite of the memory directory that `dsh-memory`
+reads.
+
+## What this package provides
+
+- **extractMemories** — an `agent/turn-stopping` listener starts a background
+  forked subagent (via `ctx.jobs` + `ctx.subagents`, read/search tools only)
+  that extracts durable facts from the turn and reports them as structured
+  output; the plugin validates the batch and writes the matching topic files
+  host-side.
+- **Dream consolidation** — three configurable gates that must all pass before
+  a read-only forked subagent reviews past sessions and reports the rewritten
+  `MEMORY.md` + topic file set the same way:
+  1. **Time** — at least `minHours` (default 24) since the last consolidation.
+  2. **Session count** — at least `minSessions` (default 5) new transcripts.
+  3. **Lock** — a `.consolidation-lock` file whose stored timestamp enforces
+     mutual exclusion; a stale holder (older than `lockStaleMs`, default 1 hour)
+     is reclaimed, so a crash mid-consolidation recovers automatically. A
+     failed or killed consolidation rolls the lock back so the time gate
+     re-opens.
+- **Memory writes change model-visible context** — upstream, `dsh-memory`
+  re-assembles the `memory` system-prompt section via `system-prompt/change`
+  after the memory directory changes. This package introduces no new session
+  events for the memory files themselves.
+
+## Sandbox interaction: why the plugin writes, not the fork
+
+Each memory directory lives in the harness home, OUTSIDE any session
+workspace. A forked subagent inherits the parent session's sandbox policy, so
+under `workspace-write` (or `read-only`) every model-side `write`/`edit`
+aimed at a memory directory is fenced (`FS_SANDBOX_DENIED`), and a
+background job cannot use the escalation retry — escalation prompts, and the
+job's approval policy is `never`. Model-side memory writes are therefore
+guaranteed to fail in any sandboxed session.
+
+So the forks hold no write tools at all. They report their file set through
+`outputSchema` (the driver-injected `structured_output` tool), and the plugin
+— trusted host code — performs the writes itself. Writes land in the TURNING
+agent's own workspace directory — `<memoryHome>/projects/<slug>/`, resolved
+from the agent's canonical git root with `resolveWorkspaceMemoryDir` — never the
+shared home root (that root is the explicitly-global layer owned by
+`dsh-memory`'s `memory_save` with `scope: "global"`):
+
+1. `validateMemoryWrites` checks the untrusted payload: flat `.md` filenames
+   only (no separators, `..`, absolute paths, or dotfiles), no duplicates,
+   and hard caps (32 files / 64 KiB per file / 256 KiB per batch). Any
+   violation rejects the WHOLE batch.
+2. `writeMemoryFiles` writes the batch via the `ctx.fs` seam, stamping a
+   per-call policy of `{ mode: 'workspace-write', workspaceRoot: <memory dir> }`
+   — confinement is kept, but the writable root IS the memory directory. The
+   sandbox still fences each write behind the validation above; nothing
+   outside the memory directory becomes writable.
+
+The job status reflects the real outcome: a non-completed `stopReason`, a
+missing/invalid payload, or a write-back failure maps to `failed` with detail
+instead of a silent fake-`completed`.
+
+## Usage
+
+Load the plugin with `@dsh-cc/memory-consolidation`. Configuration:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `memoryHome` | harness home `memory/` | memory home root; extraction/dream write into the turning agent's repository `projects/<slug>/` under it |
+| `extractEnabled` | `true` | run turn-end extraction |
+| `dreamEnabled` | `true` | run the three-gate dream |
+| `minHours` | `24` | minimum hours between consolidations |
+| `minSessions` | `5` | minimum new transcripts to consolidate |
+| `lockStaleMs` | `3_600_000` | lock holder stale window |
+| `subagentProviderName` | `fork` | one-shot provider for the forks |
+
+```ts
+import consolidation from '@dsh-cc/memory-consolidation'
+await ctx.plugin(consolidation, { minHours: 24, minSessions: 5 })
+```
+
+## Model Experience
+
+The turn-stopping listener is nearly free when the gates are closed (one lock
+read). When the time and session gates open, one forked subagent runs per
+consolidation, restricted to read/search tools plus the `structured_output`
+report tool; its output is not appended to the main transcript. Per turn,
+extraction may start a short background fork.
+
+## API
+
+- `tryAcquireLock(fs, dir, pid, now, policy?)` / `rollbackLock(fs, dir, priorAt, policy?)` /
+  `readLastConsolidatedAt(fs, dir)` — the consolidation lock.
+- `gatesPass(input)` / `timeGatePasses(...)` / `sessionGatePasses(...)` — the
+  gate predicates.
+- `MEMORY_TOOL_FILTER` / `MEMORY_AGENT_TOOLS` — the memory-scoped tool set
+  (read/search + `structured_output`).
+- `MEMORY_WRITES_SCHEMA` — the `outputSchema` contract every fork reports.
+- `validateMemoryWrites(input)` / `writeMemoryFiles(fs, dir, writes)` /
+  `memoryWritePolicy(dir)` — the host-side write-back (owned by
+  `@dsh-cc/memory`, the memory directory owner, and re-exported here).
+- `buildExtractionPrompt` / `buildConsolidationPrompt` — the fork prompts.
+
+## Known Limitations and Deferred Work
+
+- The `ctx.fs` seam exposes no mtime, so the lock stores the holder PID and
+  last-consolidated epoch in the lock file's body rather than in the file
+  mtime; crash recovery rests on the stale window, not process-liveness.
+- The session-count gate currently counts live sessions through `ctx.sessions`
+  and treats them as new; a clocked transcript query is deferred.
+- There is no delete channel: the dream drops outdated memories from
+  `MEMORY.md`, but an orphaned topic file stays on disk until overwritten.
+  Topic-file deletion is deferred (the fork allow-list never had a remove
+  tool either).
+- Concurrent extractions from parallel sessions write last-writer-wins; the
+  dream lock serializes only consolidations.

package/README.zh.md

@@ -0,0 +1,96 @@
+# dsh-memory-consolidation
+
+中文 | [English](README.md)
+
+面向 DeepSeek Harness 的后台记忆整合：轮末抽取与对 `dsh-memory` 所读取的记忆
+目录进行三重门 dream 重写。
+
+## 本包提供的能力
+
+- **extractMemories** —— `agent/turn-stopping` 监听器启动一个后台 fork 的
+  subagent（通过 `ctx.jobs` + `ctx.subagents`，仅持有读/搜索工具），从当前轮
+  抽取持久事实并以结构化输出上报；插件校验该批次后在 host 侧写入匹配的主题
+  文件。
+- **Dream 整合** —— 三道可配置的门，全部通过后才会用只读的 fork subagent 回顾
+  过往会话，并以同样方式上报重写后的 `MEMORY.md` 与主题文件集：
+  1. **时间门** —— 自上次整合起至少 `minHours`（默认 24）小时。
+  2. **会话门** —— 至少 `minSessions`（默认 5）条新 transcript。
+  3. **文件锁** —— `.consolidation-lock` 文件以存储的时间戳保证互斥；过期的持有者
+     （超过 `lockStaleMs`，默认 1 小时）可被回收，因此整合中崩溃可自动恢复。失败
+     或被 kill 的整合会回滚锁，使时间门重新打开。
+- **记忆写入改变模型可见上下文** —— 在上游，`dsh-memory` 会在记忆目录变更后通过
+  `system-prompt/change` 重组装 `memory` 系统提示词 section。本包不为记忆文件本身
+  引入新的会话事件。
+
+## 与 sandbox 的关系:为什么由插件而非 fork 落盘
+
+记忆目录位于 harness home，在任何会话 workspace 之外。fork subagent 继承父会话
+的 sandbox 策略，因此在 `workspace-write`(或 `read-only`)下,所有指向记忆目录
+的模型侧 `write`/`edit` 都会被围栏拦截(`FS_SANDBOX_DENIED`);后台 job 又无法
+走 escalation 重试——escalation 需要弹审批,而 job 的审批策略是 `never`。所以在
+任何 sandboxed 会话里,模型侧的记忆写入注定失败。
+
+因此 fork 不再持有任何写工具:它们通过 `outputSchema`(driver 注入的
+`structured_output` 工具)上报文件集,由插件——可信的 host 代码——亲自落盘。
+写入目标是**触发 agent 自己所在工作区的目录**——`<memoryHome>/projects/<slug>/`,
+由 `resolveWorkspaceMemoryDir` 按 agent 的规范 git 根解析——而不是共享的 home 根
+（home 根是显式全局层,由 `dsh-memory` 的 `memory_save` 以 `scope: "global"` 写入）:
+
+1. `validateMemoryWrites` 校验这份不可信负载:仅允许扁平 `.md` 文件名(不允许
+   分隔符、`..`、绝对路径、点文件),不允许重名,并施加硬上限(32 个文件 /
+   单文件 64 KiB / 单批 256 KiB)。任何违规整批拒绝。
+2. `writeMemoryFiles` 经 `ctx.fs` 缝写入,并为每次调用盖上
+   `{ mode: 'workspace-write', workspaceRoot: <记忆目录> }` 的 per-call 策略——
+   围栏仍然生效,只是可写根恰好就是记忆目录。sandbox 在校验之外再兜一层;
+   记忆目录之外的任何路径都不可写。
+
+job 状态反映真实结局:非 completed 的 `stopReason`、缺失/非法的负载、落盘失败
+都会映射为 `failed` 并带 detail,而不是静默地假 `completed`。
+
+## 使用
+
+以 `@dsh-cc/memory-consolidation` 加载插件。配置：
+
+| Key | 默认值 | 含义 |
+|---|---|---|
+| `memoryHome` | harness home `memory/` | 记忆 home 根;抽取/dream 写入触发 agent 所在仓库的 `projects/<slug>/` |
+| `extractEnabled` | `true` | 运行轮末抽取 |
+| `dreamEnabled` | `true` | 运行三重门 dream |
+| `minHours` | `24` | 两次整合间的最小间隔小时数 |
+| `minSessions` | `5` | 需要整合的最小新 transcript 数 |
+| `lockStaleMs` | `3_600_000` | 锁持有者过期窗口 |
+| `subagentProviderName` | `fork` | fork 使用的一次性 provider |
+
+```ts
+import consolidation from '@dsh-cc/memory-consolidation'
+await ctx.plugin(consolidation, { minHours: 24, minSessions: 5 })
+```
+
+## Model Experience
+
+门关闭时，turn-stopping 监听器几乎无成本（一次锁读取）。当时间门与会话门打开时，
+每次整合运行一个 fork subagent，限制为读/搜索工具加 `structured_output` 上报工具;
+其输出不会追加到主 transcript。每轮抽取可能启动一个短暂后台 fork。
+
+## API
+
+- `tryAcquireLock(fs, dir, pid, now, policy?)` / `rollbackLock(fs, dir, priorAt, policy?)` /
+  `readLastConsolidatedAt(fs, dir)` —— 整合锁。
+- `gatesPass(input)` / `timeGatePasses(...)` / `sessionGatePasses(...)` —— 门谓词。
+- `MEMORY_TOOL_FILTER` / `MEMORY_AGENT_TOOLS` —— 记忆作用域工具集(读/搜索 +
+  `structured_output`)。
+- `MEMORY_WRITES_SCHEMA` —— 每个 fork 上报的 `outputSchema` 契约。
+- `validateMemoryWrites(input)` / `writeMemoryFiles(fs, dir, writes)` /
+  `memoryWritePolicy(dir)` —— host 侧落盘(由记忆目录的拥有者
+  `@dsh-cc/memory` 持有,此处 re-export)。
+- `buildExtractionPrompt` / `buildConsolidationPrompt` —— fork 的提示词。
+
+## 已知限制与延期工作
+
+- `ctx.fs` 缝不暴露 mtime，因此锁将持有者 PID 与上次整合时间戳存入锁文件正文而非
+  文件 mtime；崩溃恢复依赖过期窗口而非进程存活。
+- 会话门当前通过 `ctx.sessions` 统计存活会话并将其视为新会话；带时钟的 transcript
+  查询已延期。
+- 没有删除通道:dream 会把过期记忆从 `MEMORY.md` 移除,但失去引用的主题文件仍留在
+  盘上,直到被覆写。主题文件删除已延期(fork 的 allow-list 本来也没有 remove 工具)。
+- 并行会话的抽取并写时为 last-writer-wins;dream 锁只串行化整合。

package/lib/gates.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The three dream gates: time, session count, and lock. Combinable pure
+ * predicates over inputs a caller reads from the seam, plus a composite check.
+ * @module @dsh-cc/memory-consolidation/gates
+ */
+/** Inputs to the time and session gates. */
+export interface ConsolidationGateInput {
+    /** Epoch of the last consolidation (0 when none / absent lock). */
+    lastConsolidatedAt: number;
+    /** Current epoch. */
+    now: number;
+    /** Minimum hours since the last consolidation. */
+    minHours: number;
+    /** Number of transcripts touched since the last consolidation. */
+    sessionCount: number;
+    /** Minimum transcripts to review. */
+    minSessions: number;
+}
+/**
+ * Time gate: at least `minHours` since the last consolidation.
+ * @param lastConsolidatedAt - last consolidated epoch (0 opens the gate).
+ * @param now - current epoch.
+ * @param minHours - minimum elapsed hours.
+ * @returns whether the time gate passes.
+ */
+export declare function timeGatePasses(lastConsolidatedAt: number, now: number, minHours: number): boolean;
+/**
+ * Session gate: at least `minSessions` transcripts touched since the last
+ * consolidation.
+ * @param sessionCount - transcripts touched since the last consolidation.
+ * @param minSessions - minimum transcripts to review.
+ * @returns whether the session gate passes.
+ */
+export declare function sessionGatePasses(sessionCount: number, minSessions: number): boolean;
+/**
+ * Composite check: the time and session gates together. The lock gate is a
+ * separate acquisition step (see {@link tryAcquireLock}).
+ * @param input - gate inputs.
+ * @returns whether both the time and session gates pass.
+ */
+export declare function gatesPass(input: ConsolidationGateInput): boolean;
+//# sourceMappingURL=gates.d.ts.map

package/lib/gates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,4CAA4C;AAC5C,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,kBAAkB,EAAE,MAAM,CAAA;IAC1B,qBAAqB;IACrB,GAAG,EAAE,MAAM,CAAA;IACX,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAA;IAChB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAA;IACpB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,kBAAkB,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIjG;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAEpF;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAGhE"}

package/lib/gates.js

@@ -0,0 +1,39 @@
+/**
+ * The three dream gates: time, session count, and lock. Combinable pure
+ * predicates over inputs a caller reads from the seam, plus a composite check.
+ * @module @dsh-cc/memory-consolidation/gates
+ */
+/**
+ * Time gate: at least `minHours` since the last consolidation.
+ * @param lastConsolidatedAt - last consolidated epoch (0 opens the gate).
+ * @param now - current epoch.
+ * @param minHours - minimum elapsed hours.
+ * @returns whether the time gate passes.
+ */
+export function timeGatePasses(lastConsolidatedAt, now, minHours) {
+    // A zero last-consolidation means none ever happened: open the gate.
+    if (lastConsolidatedAt <= 0)
+        return true;
+    return now - lastConsolidatedAt >= minHours * 3_600_000;
+}
+/**
+ * Session gate: at least `minSessions` transcripts touched since the last
+ * consolidation.
+ * @param sessionCount - transcripts touched since the last consolidation.
+ * @param minSessions - minimum transcripts to review.
+ * @returns whether the session gate passes.
+ */
+export function sessionGatePasses(sessionCount, minSessions) {
+    return sessionCount >= minSessions;
+}
+/**
+ * Composite check: the time and session gates together. The lock gate is a
+ * separate acquisition step (see {@link tryAcquireLock}).
+ * @param input - gate inputs.
+ * @returns whether both the time and session gates pass.
+ */
+export function gatesPass(input) {
+    return timeGatePasses(input.lastConsolidatedAt, input.now, input.minHours)
+        && sessionGatePasses(input.sessionCount, input.minSessions);
+}
+//# sourceMappingURL=gates.js.map

package/lib/gates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gates.js","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAgBH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,kBAA0B,EAAE,GAAW,EAAE,QAAgB;IACtF,qEAAqE;IACrE,IAAI,kBAAkB,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IACxC,OAAO,GAAG,GAAG,kBAAkB,IAAI,QAAQ,GAAG,SAAS,CAAA;AACzD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,YAAoB,EAAE,WAAmB;IACzE,OAAO,YAAY,IAAI,WAAW,CAAA;AACpC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,KAA6B;IACrD,OAAO,cAAc,CAAC,KAAK,CAAC,kBAAkB,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,CAAC;WACrE,iBAAiB,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,CAAA;AAC/D,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Background memory consolidation: turn-end extraction and the three-gate
+ * dream rewrite.
+ *
+ * `agent/turn-stopping` fires an extraction subagent (via `ctx.jobs` +
+ * `ctx.subagents`, tools restricted to read/search) that reports durable facts
+ * as structured output, and evaluates the dream gates (time, session count,
+ * lock) to schedule a read-only review whose structured output rewrites
+ * MEMORY.md and the topic files. The forks hold no write tools — the memory
+ * directory sits outside the session workspace, so the fs sandbox would fence
+ * every model-side write with no escalation path from a background job; the
+ * plugin validates each reported batch and writes it host-side under a
+ * per-call policy confined to the memory directory (see `writeback.ts`). A
+ * failed dream rolls back the lock so the time gate re-opens.
+ *
+ * @module @dsh-cc/memory-consolidation
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export { LOCK_FILE, LOCK_STALE_MS, readLastConsolidatedAt, rollbackLock, tryAcquireLock } from './lock.ts';
+export { gatesPass, timeGatePasses, sessionGatePasses } from './gates.ts';
+export type { ConsolidationGateInput } from './gates.ts';
+export { MEMORY_AGENT_TOOLS, MEMORY_TOOL_FILTER } from './tools.ts';
+export { buildConsolidationPrompt, buildExtractionPrompt } from './prompts.ts';
+export { MEMORY_WRITES_SCHEMA, WRITEBACK_MAX_FILE_BYTES, WRITEBACK_MAX_FILES, WRITEBACK_MAX_TOTAL_BYTES, memoryWritePolicy, validateMemoryWrites, writeMemoryFiles, } from '@dsh-cc/memory';
+export type { MemoryWrite, MemoryWritePolicy } from '@dsh-cc/memory';
+export declare const name = "memory-consolidation";
+/** Services required for background jobs and the subagent provider. */
+export declare const inject: string[];
+/** Memory consolidation configuration. */
+export interface Config {
+    /** Memory directory root. Defaults to the harness home `memory/`. */
+    memoryHome?: string;
+    /** Turn-end extraction runs (default true). */
+    extractEnabled?: boolean;
+    /** The three-gate dream runs (default true). */
+    dreamEnabled?: boolean;
+    /** Minimum hours between consolidations (default 24). */
+    minHours?: number;
+    /** Minimum new transcripts to consolidate (default 5). */
+    minSessions?: number;
+    /** A lock holder is stale past this window (default 1 hour). */
+    lockStaleMs?: number;
+    /** One-shot subagent provider for forks (default `fork`). */
+    subagentProviderName?: string;
+}
+export declare const Config: z<Config>;
+/**
+ * Register the consolidation plugin.
+ * @param ctx - the host context with jobs, subagents, fs, and sessions.
+ * @param config - consolidation behavior knobs.
+ */
+export declare function apply(ctx: Context, config?: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAiBxC,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,sBAAsB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC1G,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACzE,YAAY,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AACxD,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AACnE,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAG9E,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAEpE,eAAO,MAAM,IAAI,yBAAyB,CAAA;AAC1C,uEAAuE;AACvE,eAAO,MAAM,MAAM,UAAwB,CAAA;AAE3C,0CAA0C;AAC1C,MAAM,WAAW,MAAM;IACrB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,gDAAgD;IAChD,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6DAA6D;IAC7D,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAQ3B,CAAA;AAyHF;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI,CAkD7D"}