stable-harness 0.0.7 → 0.0.9

package/docs/memory/0.1.0-step-09-deepagents-native-memory.zh.md

@@ -0,0 +1,146 @@
+# 0.1.0 Step 09.7 DeepAgents Native Memory Support
+
+## 目标
+
+本步骤支持 DeepAgents 原生 memory 和 DeepAgents 生态里的 memory substrate。stable-harness 不重新定义这些上游语义，只做 runtime assembly 和 adapter pass-through。
+
+## DeepAgents 原生支持
+
+DeepAgents `createDeepAgent` 支持：
+
+```text
+memory?: string[]
+backend?: AnyBackendProtocol | BackendFactory
+store?: BaseStore
+checkpointer?: BaseCheckpointSaver | boolean
+middleware?: AgentMiddleware[]
+skills?: string[]
+```
+
+其中：
+
+- `memory` 是 memory source path 列表，通常指向 `AGENTS.md` 这类文件。
+- `backend` 是 DeepAgents 用来读取 memory/skills/files 的 backend。
+- `store` 是 LangGraph/LangChain long-term store。
+- `checkpointer` 是 run/thread state persistence，不等同于长期记忆。
+- `middleware` 可以直接包含 DeepAgents `createMemoryMiddleware(...)` 产物。
+
+## stable-harness 配置
+
+YAML / config 可以写：
+
+```yaml
+config:
+  deepagents:
+    memory:
+      - /memories/user/AGENTS.md
+      - /memories/project/AGENTS.md
+    skills:
+      - /skills/project/
+```
+
+兼容别名：
+
+```yaml
+config:
+  deepagents:
+    memorySources:
+      - /memories/project/AGENTS.md
+    skillSources:
+      - /skills/project/
+```
+
+程序化使用可以直接传对象：
+
+```ts
+agent.config.deepagents = {
+  backend,
+  store,
+  checkpointer,
+  middleware: [
+    createMemoryMiddleware({ backend, sources: ["/memories/project/AGENTS.md"] })
+  ]
+};
+```
+
+## 边界
+
+DeepAgents native memory：
+
+```text
+file/source based memory
+middleware injection
+backend/store/checkpointer substrate
+upstream system prompt integration
+```
+
+stable-harness typed memory：
+
+```text
+MemoryCandidate
+MemoryDecision
+MemoryRecord
+policy
+approval
+persistence
+maintenance
+	upstream config mapping
+```
+
+二者关系：
+
+```text
+stable typed memory -> recall context -> runtime events / adapter context
+DeepAgents native memory -> upstream createDeepAgent params/middleware
+```
+
+不要把 DeepAgents `memory?: string[]` 当作 stable-harness 的 public memory record schema。
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  participant Workspace
+  participant Adapter as DeepAgents Adapter
+  participant DeepAgents as createDeepAgent
+  participant Backend as DeepAgents Backend
+
+  Workspace->>Adapter: config.deepagents.memory / backend / store
+  Adapter->>DeepAgents: pass-through createDeepAgent params
+  DeepAgents->>Backend: load memory source paths
+  Backend-->>DeepAgents: AGENTS.md memory content
+  DeepAgents->>DeepAgents: inject native memory into system prompt
+```
+
+## Flow Chart
+
+```mermaid
+flowchart TD
+  A["Agent config"] --> B{"deepagents.memory or memorySources?"}
+  B -->|yes| C["Pass memory string[] to createDeepAgent"]
+  B -->|no| D["No native DeepAgents memory source"]
+  A --> E{"backend/store/checkpointer/middleware?"}
+  E -->|yes| F["Pass through upstream objects"]
+  E -->|no| G["Use DeepAgents defaults"]
+  C --> H["DeepAgents upstream memory middleware"]
+  F --> H
+  D --> H
+  G --> H
+```
+
+## Verification
+
+本步骤新增测试覆盖：
+
+- `deepagents.memory` 透传为 `createDeepAgent({ memory })`。
+- `deepagents.skills` 透传为 `createDeepAgent({ skills })`。
+- `deepagents.backend`、`store`、`checkpointer`、`middleware`、`permissions` 透传。
+- 真实 `deepagents@1.9.1` + 远端 Ollama `granite4.1:3b` 默认路径仍通过。
+
+验证命令：
+
+```text
+npm run check
+npm run check:rules
+npm test
+```

package/docs/memory/0.1.0-step-09-langmem-shaped-provider.zh.md

@@ -0,0 +1,169 @@
+# 0.1.0 Step 09.8 LangMem-Shaped Provider Contract
+
+## 目标
+
+本步骤把 stable-harness 的 memory provider contract 按 LangMem 语义定义，同时允许两个实现方向：
+
+- Python LangMem service provider。
+- JS embedded provider。
+
+核心原则：同一套定义，不同 provider 实现。
+
+## Config Surface
+
+```yaml
+memory:
+  provider: embedded
+  mode:
+    hotPathTools: true
+    backgroundManager: true
+  types:
+    semantic: true
+    episodic: true
+    procedural: true
+  approval:
+    procedural: true
+    sensitive: true
+    restricted: true
+  defaults:
+    scope: workspace
+    sensitivity: internal
+```
+
+## Provider Interface
+
+```text
+MemoryProvider
+├─ name
+├─ config
+├─ propose(input) -> MemoryCandidate[]
+├─ search(input) -> MemoryRecord[]
+└─ consolidate(input) -> MemoryMaintenanceOperation[]
+```
+
+## Mode
+
+- `hotPathTools`：允许执行路径中暴露 memory search/manage 工具。
+- `backgroundManager`：允许 run 后台做 extraction、consolidation、cleanup。
+
+当前只定义开关，不自动注册工具或后台任务。
+
+## Types
+
+- `semantic`：事实、偏好、知识。
+- `episodic`：某次运行、事件、验证结果。
+- `procedural`：未来行为规则和操作流程。
+
+Provider 可以提出这些类型，但 stable-harness policy 仍是最终决策层。
+
+## Approval
+
+- `procedural`：影响未来行为，默认应审批。
+- `sensitive`：敏感信息，默认应审批。
+- `restricted`：高风险信息，默认应审批或拒绝。
+
+## Embedded JS Provider
+
+当前内置 `createEmbeddedMemoryProvider(config)`：
+
+- 不使用 LLM。
+- 根据 typed config 过滤 memory kind。
+- `propose` 生成 `MemoryCandidate`。
+- `search` 通过 `RuntimeMemoryStore.recall`。
+- `consolidate` 把 stale record 转成 archive operation。
+
+它是 MVP，用于本地开发和测试，不替代 LangMem。
+
+## Python LangMem Service Provider
+
+后续 Python service 应实现同一个 contract：
+
+```text
+POST /memory/propose
+POST /memory/search
+POST /memory/consolidate
+GET  /health
+```
+
+服务职责：
+
+- 调用 LangMem Python SDK。
+- 做 semantic / episodic / procedural extraction。
+- 做 consolidation suggestion。
+- 返回 candidates 或 maintenance operations。
+
+服务不负责最终 store/reject/review。最终决策仍由 stable-harness policy 和 approval queue 完成。
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  participant Runtime
+  participant Provider as MemoryProvider
+  participant Policy as MemoryPolicy
+  participant Store as RuntimeMemoryStore
+
+  Runtime->>Provider: propose(run content)
+  Provider-->>Runtime: MemoryCandidate[]
+  Runtime->>Policy: decide(candidate)
+  Policy-->>Runtime: MemoryDecision
+  alt store
+    Runtime->>Store: submitCandidate(candidate)
+  else review
+    Runtime->>Runtime: approval queue
+  else reject
+    Runtime->>Runtime: audit rejection
+  end
+```
+
+## Flow Chart
+
+```mermaid
+flowchart TD
+  A["Run or tool evidence"] --> B{"provider"}
+  B -->|embedded| C["JS embedded provider"]
+  B -->|langmem-service| D["Python LangMem service"]
+  C --> E["MemoryCandidate[]"]
+  D --> E
+  E --> F["stable-harness MemoryPolicy"]
+  F --> G{"decision"}
+  G -->|store| H["RuntimeMemoryStore"]
+  G -->|review| I["ApprovalQueue"]
+  G -->|reject| J["Audit event"]
+```
+
+## Verification
+
+本步骤新增测试覆盖：
+
+- `createEmbeddedMemoryProvider` 接受 LangMem-shaped config。
+- disabled procedural type 会拒绝 procedural candidate。
+- semantic candidate 可以产生并存入 runtime store。
+- provider search 走 runtime store recall。
+- provider consolidate 把 stale record 转为 archive operation。
+
+验证命令：
+
+```text
+npm run check
+npm run check:rules
+npm test
+```
+
+## 下游验证
+
+本步骤已完成 EasyNet 真实验证：
+
+```text
+cd /Users/boqiangliang/project/easynet
+npm test
+npm run test:botbotgo:full
+```
+
+真实验证结果：
+
+- `npm test` 通过：18 个 contract tests，7 个 real integration tests。
+- `test:botbotgo:full` 通过：8/8 matrix cases。
+- full matrix 明确使用 EasyNet package-local `node_modules/.bin/botbotgo`。
+- 真实模型路径为 EasyNet 配置的远端 Ollama `granite4.1:3b`。
+- 覆盖 owner：orchestra、software、qa、ops、release、research、secretary、k8s。

package/docs/memory/0.1.0-step-09-memory-adapter-projection.zh.md

@@ -0,0 +1,123 @@
+# 0.1.0 Step 09.3 Memory Adapter Boundary
+
+## 目标
+
+本步骤定义 runtime memory 与 DeepAgents adapter 的边界：stable runtime 可以执行 recall 并把 typed memory context 交给 adapter，但 adapter 不把 recall 文本拼进 `systemPrompt`。DeepAgents 原生 memory 能力通过 upstream-native config 或 middleware 接入。
+
+## 设计边界
+
+core runtime 负责：
+
+- 执行 memory recall。
+- 把 recall records 和 compressed context 放入 `RuntimeAdapterContext.memory`。
+- 发出 `runtime.memory.recall.completed` 和 `runtime.memory.lifecycle` 事件。
+
+DeepAgents adapter 负责：
+
+- 读取 `RuntimeAdapterContext.memory`。
+- 把 `agent.config.deepagents.memory`、`memorySources`、`middleware`、`store` 等 upstream-native 配置传给 `createDeepAgent`。
+- 不把 stable runtime recall context 写入 prompt。
+
+不做：
+
+- 不暴露 DeepAgents `/memories/` 作为 stable-harness public API。
+- 不默认把 memory 注入 prompt。
+- 不从 agent 输出中自动抽取 memory。
+- 不用 memory 改写 routing、tool calling 或 subagent planning。
+- 不把业务领域知识写入 runtime。
+
+## Interface
+
+```text
+RuntimeAdapterContext
+└─ memory?
+   ├─ namespace
+   ├─ records
+   └─ context
+
+Agent config
+└─ deepagents
+   ├─ memory?: string[]
+   ├─ memorySources?: string[]
+   ├─ middleware?: unknown[]
+   └─ store?: unknown
+```
+
+## Adapter 行为
+
+DeepAgents adapter 的 memory 处理只有两类：
+
+- `RuntimeAdapterContext.memory` 保持为 typed runtime context，可用于事件、审计、评估或未来显式 adapter extension。
+- DeepAgents 原生 memory 通过 `agent.config.deepagents` 透传给 upstream `createDeepAgent`。
+- adapter 不拼接 recall 文本到 `systemPrompt`。
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  participant Runtime
+  participant Memory as RuntimeMemoryStore
+  participant Adapter as DeepAgents Adapter
+  participant Upstream as createDeepAgent
+
+  Runtime->>Memory: recall(namespace, query)
+  Memory-->>Runtime: records + context
+  Runtime->>Adapter: run(context.memory)
+  Adapter->>Upstream: createDeepAgent(upstream-native memory config)
+```
+
+## Flow Chart
+
+```mermaid
+flowchart TD
+  A["Adapter receives RuntimeAdapterContext"] --> B{"memory context exists?"}
+  B --> C["Keep context typed; do not alter prompt"]
+  C --> D["Pass deepagents.memory / middleware / store to upstream"]
+  D --> E["createDeepAgent(params)"]
+```
+
+## Verification
+
+本步骤新增测试覆盖：
+
+- DeepAgents adapter 不把 runtime memory 写入 prompt。
+- DeepAgents native memory config 仍透传给 upstream，不产生 prompt 注入。
+- adapter 仍通过 upstream `createDeepAgent` 路径执行。
+- stable runtime 仍不暴露 DeepAgents `/memories/`。
+- 安装 `deepagents@1.9.1` 后，adapter 默认路径真实 import 上游包并使用远端 Ollama `granite4.1:3b` 完成一次真实调用。
+
+验证命令：
+
+```text
+npm run check
+npm run check:rules
+npm test
+```
+
+## 下游验证
+
+本步骤已完成 EasyNet 真实验证：
+
+```text
+cd /Users/boqiangliang/project/easynet
+npm test
+npm run test:botbotgo:full
+```
+
+真实验证结果：
+
+- `npm test` 通过：18 个 contract tests，7 个 real integration tests。
+- `test:botbotgo:full` 通过：8/8 matrix cases。
+- full matrix 明确使用 EasyNet package-local `node_modules/.bin/botbotgo`。
+- 真实模型路径为 EasyNet 配置的远端 Ollama `granite4.1:3b`。
+- stable-harness 自身测试真实调用 `deepagents@1.9.1` + `@langchain/ollama` + `https://ollama-rtx-4070.easynet.world/`。
+- 覆盖 owner：orchestra、software、qa、ops、release、research、secretary、k8s。
+- 覆盖真实工具/数据路径：finance stock report、source analysis、disk investigation、Git/GitHub Actions、Kubernetes readonly investigation、CLI routing。
+
+## 下一步
+
+下一步是 `Step 09.4 Memory Governance And Approval`：
+
+- 把 sensitive/restricted memory review 接入 governance approval queue。
+- 为 memory decision 增加 operator-visible audit event。
+- 继续保持模型只能提出 candidate，runtime policy 决定最终动作。

package/docs/memory/0.1.0-step-09-memory-contract.zh.md

@@ -0,0 +1,169 @@
+# 0.1.0 Step 09.1 长期记忆 Runtime Contract
+
+## 目标
+
+本步骤为 `stable-harness` 建立长期记忆的第一层 runtime contract。它只定义 runtime 应该如何接收、决策、存储、召回和审计 memory，不接管 DeepAgents、OpenAI Agents SDK、Gemini SDK 等上游框架的执行语义。
+
+当前实现刻意保持很小：
+
+- `MemoryCandidate`：agent、tool、run 或 operator 提出的待记忆内容。
+- `MemoryDecision`：runtime policy 对候选内容做出的确定性决策。
+- `MemoryRecord`：runtime 接受后的稳定记录。
+- `MemoryPolicy`：决定 store、reject、review 等动作。
+- `RuntimeMemoryStore`：提交候选、直接记忆、召回、列出、更新、归档。
+- `createInMemoryRuntimeMemoryStore`：第一阶段内存实现，用于 contract 测试和后续 adapter 集成前验证。
+
+## 边界
+
+`stable-harness` 拥有 memory lifecycle、policy、namespace、approval、audit 和 adapter context。上游框架拥有 agent 执行语义和 prompt/memory 注入方式。
+
+本步骤不实现：
+
+- 不实现 DeepAgents `/memories/` 作为 public API。
+- 不把 memory 做成不断增长的 prompt blob。
+- 不用 memory 做自然语言 keyword routing。
+- 不实现业务领域规则，例如股票、新闻、Kubernetes、release、finance。
+- 不 replay 上游 tool call。
+- 不发明第二套 subagent planning language。
+- 不把 vector store 当成 source of truth。
+
+## Interface
+
+```text
+@stable-harness/memory
+├─ MemoryCandidate
+│  ├─ namespace
+│  ├─ content
+│  ├─ sourceType / sourceRef
+│  ├─ kindHint
+│  ├─ scopeHint
+│  ├─ confidenceHint
+│  ├─ sensitivity
+│  ├─ noStore
+│  └─ provenance / metadata
+│
+├─ MemoryDecision
+│  ├─ action
+│  ├─ reason
+│  ├─ kind / scope
+│  ├─ confidence
+│  ├─ retrievalPriority
+│  └─ reviewRequired
+│
+├─ MemoryRecord
+│  ├─ id / canonicalKey
+│  ├─ namespace
+│  ├─ kind / scope / status
+│  ├─ content / summary
+│  ├─ confidence
+│  ├─ sourceRefs / tags
+│  ├─ sensitivity
+│  ├─ createdAt / observedAt / lastConfirmedAt
+│  ├─ revision
+│  └─ supersedes / conflictsWith
+│
+├─ MemoryPolicy
+│  └─ decide(candidate)
+│
+└─ RuntimeMemoryStore
+   ├─ submitCandidate(candidate)
+   ├─ memorize(input)
+   ├─ recall(input)
+   ├─ list(input)
+   ├─ update(input)
+   └─ archive(id)
+```
+
+## 当前 Policy
+
+第一阶段 policy 是 deterministic policy：
+
+- `noStore: true` 直接 `reject`。
+- 空内容直接 `reject`。
+- `sensitive` 或 `restricted` 进入 `review`，不直接写入 store。
+- 其他候选内容进入 `store`。
+- 默认 `kind = semantic`，`scope = workspace`，`confidence = 0.6`。
+
+这保证小模型或上游 agent 只能提出候选，最终是否成为 durable memory 由 runtime policy 决定。
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  participant Source as Agent/Tool/Run
+  participant Store as RuntimeMemoryStore
+  participant Policy as MemoryPolicy
+  participant Record as MemoryRecord
+
+  Source->>Store: submitCandidate(candidate)
+  Store->>Policy: decide(candidate)
+  Policy-->>Store: MemoryDecision
+  alt action is store
+    Store->>Record: create active record
+    Store-->>Source: decision + record
+  else action is review
+    Store-->>Source: decision only
+  else action is reject
+    Store-->>Source: rejection decision
+  end
+```
+
+## Flow Chart
+
+```mermaid
+flowchart TD
+  A["MemoryCandidate"] --> B{"noStore or empty?"}
+  B -->|yes| C["reject"]
+  B -->|no| D{"sensitive or restricted?"}
+  D -->|yes| E["review required"]
+  D -->|no| F["store"]
+  F --> G["MemoryRecord active"]
+  G --> H["recall filters by namespace/scope/kind/status"]
+  H --> I["compressed context"]
+```
+
+## Verification
+
+本步骤已完成的验证：
+
+```text
+npm run check
+npm run check:rules
+npm test
+```
+
+覆盖内容：
+
+- memory direct write。
+- candidate submit。
+- sensitive candidate review。
+- recall records。
+- recall compressed context。
+- governance/tool policy 原有测试未回退。
+
+EasyNet 下游真实验证：
+
+```text
+cd /Users/boqiangliang/project/easynet
+npm test
+npm run test:botbotgo:full
+```
+
+真实验证结果：
+
+- EasyNet 使用 `file:../stable-harness` 依赖当前本地 runtime。
+- botbotgo full matrix 明确使用 EasyNet package-local `node_modules/.bin/botbotgo`。
+- 模型路径为远端 Ollama `granite4.1:3b`，配置来自 EasyNet `config/models.yaml`。
+- `npm test` 通过：18 个 contract tests，7 个 real integration tests。
+- `test:botbotgo:full` 通过：8/8 matrix cases。
+- 覆盖 owner：orchestra、software、qa、ops、release、research、secretary、k8s。
+- 覆盖真实工具/数据路径：finance stock report、web/source analysis、disk investigation、Git/GitHub Actions、Kubernetes readonly investigation、CLI routing。
+
+## 下一步
+
+下一步应实现 `Step 09.2 Memory Lifecycle Hooks`：
+
+- 在 core runtime 增加 memory event 类型。
+- 在 request lifecycle 中预留 `read-before-plan`、`read-before-finalize`、`write-after-run` hook。
+- hook 只产生 typed events 和 memory candidate，不改变 backend execution semantics。
+- 完成后运行 stable-harness 测试，并接 EasyNet 真实模型、真实工具、真实数据跑完整 E2E。