openclaw-cortex-memory 0.1.0-Alpha.12 → 0.1.0-Alpha.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/README.md +85 -144
  2. package/SKILL.md +1 -1
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +83 -33
  5. package/dist/index.js.map +1 -1
  6. package/dist/openclaw.plugin.json +1 -1
  7. package/dist/src/engine/ts_engine.d.ts.map +1 -1
  8. package/dist/src/engine/ts_engine.js +32 -5
  9. package/dist/src/engine/ts_engine.js.map +1 -1
  10. package/dist/src/store/vector_store.d.ts.map +1 -1
  11. package/dist/src/store/vector_store.js +17 -3
  12. package/dist/src/store/vector_store.js.map +1 -1
  13. package/openclaw.plugin.json +1 -1
  14. package/package.json +1 -1
package/README.md CHANGED
@@ -1,65 +1,54 @@
1
1
  # OpenClaw Cortex Memory
2
2
 
3
- 面向 OpenClaw 的长期记忆插件，集成多路检索、事件归档、图谱关系、向量化与反衰减排序，支持历史增量导入、规则反思和可观测诊断，帮助 Agent 在跨会话中持续积累并稳定调用高价值记忆。
3
+ OpenClaw 长期记忆插件 - 专为 OpenClaw AI 助手设计的智能记忆系统
4
4
 
5
- 发布签名见 [SIGNATURE.md]
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
6
+ [![Node.js: 22+](https://img.shields.io/badge/Node.js-22+-green.svg)](https://nodejs.org/)
7
+ [![OpenClaw: Plugin](https://img.shields.io/badge/OpenClaw-Plugin-orange.svg)](https://github.com/openclaw)
6
8
 
7
- ## 功能特性
9
+ 面向 OpenClaw 的长期记忆插件，集成多路检索、事件归档、图谱关系、向量化与反衰减排序，支持历史增量导入、规则反思和可观测诊断，帮助 Agent 在跨会话中持续积累并稳定调用高价值记忆。
8
10
 
9
- | 特性 | 说明 |
10
- |------|------|
11
- | 语义检索 | `search_memory` 支持 query + top_k |
12
- | 事件存储 | `store_event` 将摘要写入归档 |
13
- | 全文分块向量化 | Active 与 Archive 统一按 `chunk_size/chunk_overlap` 做全文分块向量化 |
14
- | 上下文注入 | `get_hot_context` / `get_auto_context` |
15
- | 增量同步 | `sync_memory` 按状态文件增量导入，并统一走 LLM 提取后写入事件/图谱 |
16
- | 向量回填重建 | `backfill_embeddings` 支持 incremental / vector_only / full 三种模式 |
17
- | 规则演进 | `reflect_memory` 更新 `CORTEX_RULES.md` |
18
- | 运行诊断 | `diagnostics` 检查本地存储状态 |
19
-
20
- ## 记忆库组成与特点
21
-
22
- ### 组成结构
23
-
24
- | 层级 | 核心文件/数据 | 作用 |
25
- |------|---------------|------|
26
- | 会话记忆层 | `sessions/active/sessions.jsonl` | 存储最近会话消息，支撑实时检索与上下文注入 |
27
- | 事件归档层 | `sessions/archive/sessions.jsonl` | 存储已沉淀事件（摘要、实体、结果），用于长期回顾 |
28
- | 实体关系层 | 基于归档事件中的 `entities` / `relations` 字段动态构图 | 支撑 `query_graph` 的实体共现与关系查询（派生图谱，不单独落盘） |
29
- | 向量检索层 | `vector/lancedb`（可用时）或 `vector/lancedb_events.jsonl`（回退） | 存储 active/archive 全文分块向量（含 `source_memory_id` 与 chunk 元信息），用于语义检索与同源融合 |
30
- | 规则知识层 | `CORTEX_RULES.md` | 存储由反思生成的可复用规则，供后续任务复用 |
31
- | 运行状态层 | `.sync_state.json` / `.session_end_state.json` / `.rule_store_state.json` / `.dedup_index.json` / `graph/mutation_log.jsonl` | 记录增量同步、session_end 幂等、规则去重、三阶段去重索引、图谱变更审计日志 |
32
- | 说明与入口层 | `MEMORY.md` | 记忆库说明与使用约定入口 |
33
-
34
- ### 核心特点
35
-
36
- - 分层记忆：把“原始会话、结构化事件、抽象规则”拆分存储，便于分别检索与治理
37
- - 图谱派生：实体关系来自事件层的 `entities` / `relations`，查询时动态生成图结构
38
- - 图谱治理：写入前按 `schema/graph.schema.yaml` 做 event/relation 规范化与关系规则校验
39
- - 会话结束写入：message hook 默认仅缓存，会在 `session_end` 后批量抽取并落盘
40
- - 严格导入门禁：历史导入内容必须经 LLM 提取判定后才写入事件层与图谱层
41
- - 增量导入：通过状态文件只处理新增会话内容，避免全量重复扫描
42
- - 幂等去重：对 session_end 事件和规则写入做签名判重，减少重复沉淀
43
- - 三阶段去重：SimHash 预过滤 → MinHash 精比对 → 向量余弦相似度
44
- - 全文分块向量化：active/archive 两层统一使用可配置 chunk 策略（默认 `600/100`，语义断句优先）
45
- - 混合检索：关键词/BM25 + 向量召回统一融合重排，并支持长度归一化防止长文本天然占优
46
- - 自动演进：可结合 `autoSync`、`autoReflect` 持续把会话经验转化为长期可复用记忆
47
- - 可观测可诊断：通过 `diagnostics` 与状态文件快速定位数据目录、同步与反思异常
48
-
49
- ## 安装
11
+ ---
12
+
13
+ ## ✨ 特性
14
+
15
+ ### 🔍 语义检索
16
+ - **多路召回**: 关键词/BM25 + 向量召回统一融合重排
17
+ - **智能排序**: 支持长度归一化防止长文本天然占优
18
+ - **反衰减机制**: 命中频次反衰减，避免高价值老记忆被过度遗忘
19
+
20
+ ### 📝 事件存储
21
+ - **分层记忆**: 原始会话、结构化事件、抽象规则拆分存储
22
+ - **全文分块向量化**: Active 与 Archive 统一按 `chunk_size/chunk_overlap` 做全文分块向量化
23
+ - **增量同步**: 按状态文件增量导入，避免全量重复扫描
24
+
25
+ ### 🕸️ 图谱关系
26
+ - **实体关系层**: 基于归档事件中的 `entities` / `relations` 字段动态构图
27
+ - **图谱治理**: 写入前按 `schema/graph.schema.yaml` 做规范化与关系规则校验
28
+ - **关系查询**: 支撑 `query_graph` 的实体共现与关系查询
29
+
30
+ ### ⚙️ 规则演进
31
+ - **自动反思**: `reflect_memory` 自动将事件转化为规则
32
+ - **规则去重**: 对规则写入做签名判重，减少重复沉淀
33
+ - **可复用规则**: 存储于 `CORTEX_RULES.md` 供后续任务复用
34
+
35
+ ### 🔧 运维诊断
36
+ - **系统诊断**: `diagnostics` 检查本地存储状态与 API 连通性
37
+ - **向量回填**: `backfill_embeddings` 支持 incremental / vector_only / full 三种模式重建向量层
38
+ - **可观测性**: 通过状态文件快速定位数据目录、同步与反思异常
39
+
40
+ ---
41
+
42
+ ## 🚀 快速开始
50
43
 
51
44
  ### 前置要求
52
45
 
53
46
  - Node.js 22+
54
47
  - OpenAI API Key（或其他兼容 API）
55
48
 
56
- ### 安装步骤
49
+ ### 安装
57
50
 
58
- 命令前缀说明：
59
- - 若你是全局安装 OpenClaw，请直接使用 `openclaw ...`
60
- - 若你使用源码安装的 OpenClaw ，请使用 `pnpm openclaw ...`
61
-
62
- 快速安装（推荐，显式来源）：
51
+ **快速安装（推荐）:**
63
52
 
64
53
  ```bash
65
54
  cd ~/openclaw
@@ -67,52 +56,33 @@ openclaw plugins install clawhub:openclaw-cortex-memory
67
56
  openclaw plugins enable openclaw-cortex-memory
68
57
  ```
69
58
 
70
- npm 安装方式：
59
+ **npm 安装方式:**
71
60
 
72
61
  ```bash
73
62
  cd ~/openclaw
74
63
  openclaw plugins install openclaw-cortex-memory@alpha
75
64
  openclaw plugins enable openclaw-cortex-memory
76
65
  ```
77
-
78
- 第三种安装方式（当 ClawHub/npm 解析受网络影响时）：
66
+ **本地包安装方式（当 ClawHub/npm 解析受网络影响时）:**
79
67
 
80
68
  ```bash
81
- curl -L -o /tmp/cortex.tgz https://registry.npmjs.org/openclaw-cortex-memory/-/openclaw-cortex-memory-0.1.0-Alpha.12.tgz
69
+ curl -L -o /tmp/cortex.tgz https://registry.npmjs.org/openclaw-cortex-memory/-/openclaw-cortex-memory-0.1.0-Alpha.14.tgz
82
70
  cd ~/openclaw
83
71
  openclaw plugins install /tmp/cortex.tgz
84
72
  openclaw plugins enable openclaw-cortex-memory
85
73
  rm -f /tmp/cortex.tgz
86
74
  ```
87
75
 
88
- 后续更新：
89
-
90
- ```bash
91
- cd ~/openclaw
92
- rm -rf ~/.openclaw/extensions/openclaw-cortex-memory
93
- openclaw plugins install clawhub:openclaw-cortex-memory
94
- openclaw plugins enable openclaw-cortex-memory
95
- ```
96
-
97
- 说明：
98
- - 推荐显式安装来源，减少 ClawHub-first 时代的来源歧义。
99
- - 使用 `plugins install` 的安装记录方式，避免 `loaded without install/load-path provenance`。
100
- - 保持 `plugins.allow` 显式包含 `openclaw-cortex-memory`，避免运行时把插件判定为未绑定信任源。
101
- - 若 `plugins install openclaw-cortex-memory` 在 ClawHub 解析阶段失败，可使用上述 tgz 方式直接安装。
102
-
103
-
104
- ### 本地开发模式（无安装记录）
76
+ **本地开发模式:**
105
77
 
106
78
  ```bash
107
79
  cd ~/.openclaw/extensions
108
80
  git clone https://github.com/deki18/openclaw-cortex-memory.git
109
81
  cd openclaw-cortex-memory
110
- npm install
82
+ npm install && npm run build
111
83
  ```
112
84
 
113
- `npm install` 不会自动构建 `dist/`，源码模式请显式执行 `npm run build`，且这种方式默认不写 OpenClaw 安装记录。
114
-
115
- ## 配置
85
+ ### 配置
116
86
 
117
87
  在 `openclaw.json` 中添加：
118
88
 
@@ -165,43 +135,6 @@ npm install
165
135
  }
166
136
  ```
167
137
 
168
- ### 关键功能开关（建议显式配置）
169
-
170
- - `readFusion.enabled`：开启多路召回后 LLM 融合
171
- - `readFusion.authoritative`：开启后仅返回融合后的权威记忆包
172
- - `readFusion.channelWeights/channelTopK`：控制各召回通道权重与配额
173
- - `readFusion.lengthNorm`：长度归一化参数，抑制超长文本得分偏置
174
- - `vectorChunking.chunkSize/chunkOverlap`：全文分块向量化参数（默认 `600/100`）
175
- - `memoryDecay.enabled`：开启按 `event_type` 半衰期衰减
176
- - `memoryDecay.antiDecay.enabled`：开启命中频次反衰减，避免高价值老记忆被过度衰减
177
- - `autoReflect`：建议在验证稳定后再开启；默认 `false`
178
-
179
- ### 配置项说明
180
-
181
- | 配置项 | 必填 | 说明 |
182
- |--------|------|------|
183
- | `embedding.provider` | 是 | 建议使用 `api`（统一第三方接口模式） |
184
- | `embedding.model` | 是 | 嵌入模型名称 |
185
- | `embedding.apiKey` | 是 | Embedding API Key（建议 `${EMBEDDING_API_KEY}`） |
186
- | `embedding.baseURL` | 是 | Embedding API 端点 |
187
- | `llm.provider` | 是 | 建议使用 `api` |
188
- | `llm.model` | 是 | LLM 模型名称 |
189
- | `llm.apiKey` | 是 | LLM API Key（建议 `${LLM_API_KEY}`） |
190
- | `llm.baseURL` | 是 | LLM API 端点 |
191
- | `reranker.provider` | 否 | 建议使用 `api` |
192
- | `reranker.model` | 是 | Reranker 模型名称 |
193
- | `reranker.apiKey` | 是 | Reranker API Key（建议 `${RERANKER_API_KEY}`） |
194
- | `reranker.baseURL` | 是 | Reranker API 端点 |
195
- | `engineMode` | 否 | 固定 `ts` |
196
- | `dbPath` | 否 | 数据目录，默认 `<plugin-dir>/data/memory` |
197
- | `autoSync` | 否 | 会话结束时自动同步历史记录，默认 `true` |
198
- | `autoReflect` | 否 | 自动触发记忆反思，默认 `false` |
199
- | `autoReflectIntervalMinutes` | 否 | 自动反思扫描间隔（分钟），默认 `30`，最小 `5` |
200
- | `readFusion.enabled` | 否 | 启用重排后 LLM 融合，默认 `true` |
201
- | `readFusion.authoritative` | 否 | 仅返回融合权威记忆包，默认 `true` |
202
- | `memoryDecay.enabled` | 否 | 启用按 `event_type` 的半衰期衰减，默认 `true` |
203
- | `memoryDecay.antiDecay.enabled` | 否 | 启用命中频次反衰减，默认 `true` |
204
-
205
138
  ### 启动
206
139
 
207
140
  ```bash
@@ -209,30 +142,13 @@ openclaw config validate
209
142
  openclaw gateway restart
210
143
  ```
211
144
 
212
- ### 主 Agent 注入说明
213
-
214
- 首次接入后，建议把下面这段发给主 Agent，确保其按记忆工作流执行：
215
-
216
- ```text
217
- 你已接入 Cortex Memory。请遵循以下规则：
218
- 1) 当用户询问历史对话、偏好、项目上下文时，先调用 search_memory 再回答。
219
- 2) 需要当前会话热上下文时调用 get_hot_context。
220
- 3) 需要自动召回相关记忆时调用 get_auto_context。
221
- 4) 在一件重要事情结束并形成明确结果后，再调用 store_event 记录（不要在过程进行中频繁记录）。
222
- 5) 需要实体关联关系时调用 query_graph。
223
- 6) 当任务经历“失败→调整→最终成功”时，优先用 store_event 记录失败原因与成功方案，再调用 reflect_memory 沉淀可复用规则。
224
- 7) 需要导入历史会话时调用 sync_memory。
225
- 8) 当 diagnostics 显示 active/archive 存在未向量化记录，或迁移后需要重建向量层时，调用 backfill_embeddings（按需选择 incremental/vector_only/full）。
226
- 9) 出现配置校验失败、记忆读写异常、检索结果异常或数据目录问题时，优先调用 diagnostics。
227
- 10) 同一任务内不要反复调用 store_event 或 reflect_memory；仅在关键节点或任务收尾时触发一次。
228
- 11) 不要臆造历史事实；无法确认时必须先检索。
229
- ```
145
+ ---
230
146
 
231
- ## 可用工具
147
+ ## 🛠️ 可用工具
232
148
 
233
149
  | 工具 | 说明 |
234
150
  |------|------|
235
- | `search_memory` | 语义搜索记忆库，支持 top_k 参数 |
151
+ | `search_memory` | 语义搜索记忆库，支持 query + top_k |
236
152
  | `store_event` | 存储事件，可包含实体和关系 |
237
153
  | `query_graph` | 查询实体关系图谱，支持关系过滤、方向过滤与路径查询 |
238
154
  | `get_hot_context` | 获取热上下文（CORTEX_RULES.md + 近期会话） |
@@ -243,7 +159,9 @@ openclaw gateway restart
243
159
  | `delete_memory` | 删除指定记忆 |
244
160
  | `diagnostics` | 系统诊断（含 embedding/LLM/reranker 连通性检查） |
245
161
 
246
- ## CLI 命令
162
+ ---
163
+
164
+ ## 💻 CLI 命令
247
165
 
248
166
  CLI 命令需在插件目录运行：
249
167
 
@@ -256,7 +174,9 @@ npx cortex-memory uninstall --keep-data # 卸载但保留数据
256
174
  npx cortex-memory help # 查看命令帮助
257
175
  ```
258
176
 
259
- ## 数据存储
177
+ ---
178
+
179
+ ## 📁 数据存储结构
260
180
 
261
181
  | 路径 | 说明 |
262
182
  |------|------|
@@ -271,18 +191,39 @@ npx cortex-memory help # 查看命令帮助
271
191
  | `<dbPath>/.rule_store_state.json` | 规则去重状态 |
272
192
  | `<dbPath>/.dedup_index.json` | 三阶段去重索引 |
273
193
  | `<dbPath>/.read_hit_stats.json` | 检索命中频次统计（用于反衰减增益） |
274
- | `<dbPath>/graph/mutation_log.jsonl` | 图谱写入审计日志（canonical_id/source_event_id/actor/timestamp） |
194
+ | `<dbPath>/graph/mutation_log.jsonl` | 图谱写入审计日志 |
195
+
196
+ ---
275
197
 
276
- ## 注意事项
198
+ ## 📋 核心特点
277
199
 
278
- 1. **API Key 安全**：使用 `${EMBEDDING_API_KEY}`、`${LLM_API_KEY}`、`${RERANKER_API_KEY}` 等环境变量而非硬编码
279
- 2. **向量维度**：必须与嵌入模型匹配，如 `text-embedding-3-large` 为 3072
280
- 3. **重排序**：可选配置 `reranker` 以提升检索精度
281
- 4. **外部传输**：检索与反思会调用你配置的 embedding/llm/reranker endpoint，请使用可信服务并最小化密钥权限
282
- 5. **会话数据**：启用 `autoSync` 时会读取 OpenClaw 会话文件并写入本地记忆目录，生产环境建议先小范围验证
283
- 6. **历史导入来源**：`sync_memory` 会同时导入 `<openclaw_base>/agents/main/sessions/*.jsonl` 与 `<openclaw_base>/workspace/memory/*.md`
284
- 7. **重复导入防护**：每日总结 `.md` 会按文件内容哈希标记在 `.sync_state.json`，未变化文件不会重复导入
200
+ - **分层记忆**: 把"原始会话、结构化事件、抽象规则"拆分存储，便于分别检索与治理
201
+ - **图谱派生**: 实体关系来自事件层的 `entities` / `relations`，查询时动态生成图结构
202
+ - **会话结束写入**: message hook 默认仅缓存，会在 `session_end` 后批量抽取并落盘
203
+ - **严格导入门禁**: 历史导入内容必须经 LLM 提取判定后才写入事件层与图谱层
204
+ - **三阶段去重**: SimHash 预过滤 → MinHash 精比对 → 向量余弦相似度
205
+ - **自动演进**: 可结合 `autoSync`、`autoReflect` 持续把会话经验转化为长期可复用记忆
285
206
 
286
- ## 许可证
207
+ ---
208
+
209
+ ## ⚠️ 注意事项
210
+
211
+ 1. **API Key 安全**: 使用 `${EMBEDDING_API_KEY}`、`${LLM_API_KEY}`、`${RERANKER_API_KEY}` 等环境变量而非硬编码
212
+ 2. **向量维度**: 必须与嵌入模型匹配，如 `text-embedding-3-large` 为 3072
213
+ 3. **重排序**: 可选配置 `reranker` 以提升检索精度
214
+ 4. **外部传输**: 检索与反思会调用你配置的 embedding/llm/reranker endpoint，请使用可信服务并最小化密钥权限
215
+ 5. **会话数据**: 启用 `autoSync` 时会读取 OpenClaw 会话文件并写入本地记忆目录，生产环境建议先小范围验证
216
+
217
+ ---
218
+
219
+ ## � 致谢
220
+
221
+ 感谢 [memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) 项目作者，本插件的核心想法借鉴了该项目。
222
+
223
+ ---
224
+
225
+ ## �📄 许可证
287
226
 
288
227
  MIT License
228
+
229
+ 发布签名见 [SIGNATURE.md](SIGNATURE.md)
package/SKILL.md CHANGED
@@ -61,7 +61,7 @@ openclaw gateway restart
61
61
  第三种安装方式（当 ClawHub/npm 解析受网络影响时）：
62
62
 
63
63
  ```bash
64
- curl -L -o /tmp/cortex.tgz https://registry.npmjs.org/openclaw-cortex-memory/-/openclaw-cortex-memory-0.1.0-Alpha.12.tgz
64
+ curl -L -o /tmp/cortex.tgz https://registry.npmjs.org/openclaw-cortex-memory/-/openclaw-cortex-memory-0.1.0-Alpha.14.tgz
65
65
  cd ~/openclaw
66
66
  openclaw plugins install /tmp/cortex.tgz
67
67
  openclaw plugins enable openclaw-cortex-memory
package/dist/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}
package/dist/index.js CHANGED
@@ -470,7 +470,7 @@ function normalizeIncomingMessage(payload) {
470
470
  return { text, role, source };
471
471
  }
472
472
  function resolveSessionId(context, payload) {
473
- const fromContext = typeof context.sessionId === "string" ? context.sessionId.trim() : "";
473
+ const fromContext = typeof context?.sessionId === "string" ? context.sessionId.trim() : "";
474
474
  if (fromContext)
475
475
  return fromContext;
476
476
  const data = asRecord(payload);
@@ -504,7 +504,7 @@ function resolveSessionId(context, payload) {
504
504
  ]);
505
505
  if (chatId)
506
506
  return `chat:${chatId}`;
507
- return `fallback:${context.workspaceId || "default"}:${context.agentId || "agent"}`;
507
+ return `fallback:${context?.workspaceId || "default"}:${context?.agentId || "agent"}`;
508
508
  }
509
509
  function compareVersions(a, b) {
510
510
  const partsA = a.split(".").map(Number);
@@ -1798,60 +1798,110 @@ function registerTools() {
1798
1798
  }
1799
1799
  }
1800
1800
  function sanitizeToolParametersSchemaValue(schema) {
1801
- if (Array.isArray(schema)) {
1802
- return schema.map(item => sanitizeToolParametersSchemaValue(item));
1803
- }
1804
- if (!schema || typeof schema !== "object") {
1805
- return schema;
1801
+ if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
1802
+ return {};
1806
1803
  }
1807
1804
  const source = schema;
1808
1805
  const target = {};
1809
- for (const [key, value] of Object.entries(source)) {
1810
- if (key === "patternProperties") {
1811
- continue;
1806
+ if (typeof source.type === "string") {
1807
+ target.type = source.type;
1808
+ }
1809
+ if (typeof source.description === "string" && source.description.trim()) {
1810
+ target.description = source.description;
1811
+ }
1812
+ if (Array.isArray(source.enum)) {
1813
+ const values = source.enum.filter(item => typeof item === "string" || typeof item === "number" || typeof item === "boolean" || item === null);
1814
+ if (values.length > 0) {
1815
+ target.enum = values;
1816
+ }
1817
+ }
1818
+ if (source.properties && typeof source.properties === "object" && !Array.isArray(source.properties)) {
1819
+ const sanitizedProperties = {};
1820
+ for (const [key, value] of Object.entries(source.properties)) {
1821
+ sanitizedProperties[key] = sanitizeToolParametersSchemaValue(value);
1812
1822
  }
1813
- if (key === "additionalProperties" && value && typeof value === "object") {
1814
- target[key] = true;
1815
- continue;
1823
+ target.properties = sanitizedProperties;
1824
+ }
1825
+ if (Array.isArray(source.required)) {
1826
+ const required = source.required.filter(item => typeof item === "string");
1827
+ if (required.length > 0) {
1828
+ target.required = required;
1816
1829
  }
1817
- target[key] = sanitizeToolParametersSchemaValue(value);
1830
+ }
1831
+ if (source.items && typeof source.items === "object" && !Array.isArray(source.items)) {
1832
+ target.items = sanitizeToolParametersSchemaValue(source.items);
1833
+ }
1834
+ if (typeof source.additionalProperties === "boolean") {
1835
+ target.additionalProperties = source.additionalProperties;
1836
+ }
1837
+ else if (source.additionalProperties && typeof source.additionalProperties === "object") {
1838
+ target.additionalProperties = true;
1818
1839
  }
1819
1840
  return target;
1820
1841
  }
1821
1842
  function sanitizeToolParametersSchema(schema) {
1822
1843
  const sanitized = sanitizeToolParametersSchemaValue(schema);
1823
- if (!sanitized || typeof sanitized !== "object" || Array.isArray(sanitized)) {
1824
- return {};
1844
+ if (sanitized.type !== "object") {
1845
+ sanitized.type = "object";
1846
+ }
1847
+ if (!sanitized.properties || typeof sanitized.properties !== "object" || Array.isArray(sanitized.properties)) {
1848
+ sanitized.properties = {};
1849
+ }
1850
+ if (!Array.isArray(sanitized.required)) {
1851
+ sanitized.required = [];
1852
+ }
1853
+ if (typeof sanitized.additionalProperties !== "boolean") {
1854
+ sanitized.additionalProperties = false;
1825
1855
  }
1826
1856
  return sanitized;
1827
1857
  }
1828
1858
  function registerToolCompat(tool) {
1829
1859
  if (!api)
1830
1860
  return;
1831
- const execute = async (params) => tool.execute({
1832
- args: params?.args || {},
1833
- context: params.context,
1834
- });
1835
- const handler = async (...params) => {
1836
- const first = params[0];
1837
- const second = params[1];
1838
- if (first && typeof first === "object" && "context" in first) {
1839
- return execute({
1840
- args: first.args || {},
1841
- context: first.context,
1842
- });
1861
+ const normalizeContext = (value) => {
1862
+ const contextObj = asRecord(value) || {};
1863
+ return {
1864
+ agentId: firstString([contextObj.agentId, contextObj.agent_id]) || "unknown-agent",
1865
+ workspaceId: firstString([contextObj.workspaceId, contextObj.workspace_id]) || "default",
1866
+ sessionId: firstString([contextObj.sessionId, contextObj.session_id]) || undefined,
1867
+ };
1868
+ };
1869
+ const normalizeInvocation = (first, second) => {
1870
+ const firstObj = asRecord(first);
1871
+ if (firstObj && ("context" in firstObj || "args" in firstObj)) {
1872
+ const explicitArgs = asRecord(firstObj.args);
1873
+ if (explicitArgs) {
1874
+ return {
1875
+ args: explicitArgs,
1876
+ context: normalizeContext(firstObj.context),
1877
+ };
1878
+ }
1879
+ const directArgs = { ...firstObj };
1880
+ delete directArgs.context;
1881
+ delete directArgs.args;
1882
+ return {
1883
+ args: directArgs,
1884
+ context: normalizeContext(firstObj.context),
1885
+ };
1843
1886
  }
1844
- return execute({
1845
- args: first || {},
1846
- context: (second || {}),
1887
+ return {
1888
+ args: firstObj || {},
1889
+ context: normalizeContext(second),
1890
+ };
1891
+ };
1892
+ const invoke = async (...params) => {
1893
+ const normalized = normalizeInvocation(params[0], params[1]);
1894
+ return tool.execute({
1895
+ args: normalized.args,
1896
+ context: normalized.context,
1847
1897
  });
1848
1898
  };
1849
1899
  api.registerTool({
1850
1900
  name: tool.name,
1851
1901
  description: tool.description,
1852
1902
  parameters: sanitizeToolParametersSchema(tool.parameters),
1853
- execute,
1854
- handler,
1903
+ execute: invoke,
1904
+ handler: invoke,
1855
1905
  });
1856
1906
  }
1857
1907
  function unregisterTools() {