@fuxi-ailabs/crowdmemory-codex-plugin 0.0.0-stage → 0.1.1

package/.agents/plugins/marketplace.json

@@ -0,0 +1,5 @@
+{
+  "name": "crowdmemory-codex",
+  "interface": { "displayName": "Crowd Memory" },
+  "plugins": [{ "name": "crowdmemory", "source": { "source": "local", "path": "./" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "Developer Tools" }]
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "crowdmemory",
+  "version": "0.1.1",
+  "description": "群体记忆：Codex 会话、失败召回与记忆工具",
+  "author": { "name": "cacheline", "email": "cacheline999@gmail.com" },
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./.mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "crowdmemory": {
+      "command": "node", "args": ["lib/mcp.js"], "cwd": ".",
+      "env_vars": ["CODEX_HOME", "CROWDMEMORY_ENDPOINT_FILE", "CROWDMEMORY_PROJECT", "CROWDMEMORY_PROFILE", "CROWDMEMORY_INJECT", "CROWDMEMORY_NOTES", "CROWDMEMORY_CODEX_STATE"]
+    }
+  }
+}

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.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# Crowd Memory Codex 插件
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把 Codex 的会话和工具 hooks 接到本机 Crowd Memory Runtime，提供 `memory_search`、`memory_read`、`memory_note`。
+插件只做宿主事件映射和引用资料投递，复用 `memory-adapter-core` 的协议、端点信任、脱敏、记忆工具和私有路由状态；
+不依赖其它 Agent framework 或业务工作流。
+
+要求 Node.js ≥22.18、Unix socket、Codex CLI 0.164.0（本次验证版本）。npm 包为 `@fuxi-ailabs/crowdmemory-codex-plugin@0.1.1`。
+Runtime 可继续使用已发布的 0.1.1。桌面端与企业托管策略需要单独验收；云编排环境不支持本地插件 command hooks。
+
+## 独立安装与试用
+
+在独立目录下载并解包 npm 发行包，无需全局安装、克隆源码或安装开发依赖：
+
+```bash
+mkdir CMLocalCodex
+cd CMLocalCodex
+npm pack @fuxi-ailabs/crowdmemory-codex-plugin@0.1.1 --registry=https://registry.npmjs.org
+mkdir -p plugin
+tar -xzf fuxi-ailabs-crowdmemory-codex-plugin-0.1.1.tgz -C plugin
+```
+
+可使用独立的 Codex 配置目录。以下命令只影响该目录，不覆盖现有的全局插件配置：
+
+```bash
+export CODEX_HOME="$PWD/.codex-crowdmemory"
+codex plugin marketplace add "$PWD/plugin/package" --json
+codex plugin add crowdmemory@crowdmemory-codex --json
+codex plugin list
+codex login
+export CROWDMEMORY_ENDPOINT_FILE="/absolute/runtime/state/endpoint.json"
+export CROWDMEMORY_PROJECT="my-repository"
+codex
+```
+
+先按 Runtime 文档启动记忆服务。安装后，在 Codex 的 hooks 信任提示中检查并信任本插件的 hook 定义；安装或启用插件不等于信任 hooks。
+正常使用不需要绕过 hooks 信任或沙箱。未信任时，记忆工具不能取得可靠的会话绑定，会返回不可用。
+保留 Codex 对 MCP 工具的审批策略：`PreToolUse` 只对本插件三个工具补会话字段（Codex 要求 `updatedInput` 与 `allow` 一起返回），
+不替其它工具放行，也不覆盖 MCP 自身的审批要求。不要同时注册另一个同名 `crowdmemory` MCP server。
+
+会话 A 修复问题并完成测试后，用 `memory_note` 写现象、原因、位置和实际修法；正常结束会话。
+会话 B 用 `memory_search` 查找、`memory_read` 核对来源；相关 shell 输出也可触发检索和读取，在下一次模型请求前交付引用资料。
+历史记录只是参考，当前代码仍需测试。
+
+## Codex 的接入范围
+
+| Codex 事件 | 行为 |
+|---|---|
+| SessionStart | 绑定 Runtime 会话；resume / fork 使用宿主给出的身份，已结束绑定重开 |
+| UserPromptSubmit | 首次提交调用 step.before，查询文本先脱敏 |
+| PreToolUse（三个记忆工具） | 覆盖调用参数中的会话身份，保留其它字段；MCP 工具使用该绑定调用 Runtime |
+| PostToolUse / Bash | 当前 CLI 只给 stdout：按输出检索并读取相关记录，保留出处与命中理由，不推断退出码 |
+| PostToolUse / apply_patch | 明确成功时只记录修改路径，不上传补丁或文件内容 |
+| SubagentStart / SubagentStop | 独立子会话绑定、召回及结束，保留父子关系；不按 FIFO 猜子任务 prompt |
+| SessionStart / compact | 重新交付上一次引用资料；不读取不稳定的 transcript 来伪造压缩摘要 |
+| SessionEnd | 同步结束父子会话，最长按 Codex 的 3 秒上限；Stop 不等于 SessionEnd |
+
+### 不把 stdout 当作退出状态
+
+在真实 Codex CLI 0.164.0 上，`printf 'error'; exit 2` 的 PostToolUse 也只收到字符串 `error`，没有退出码。
+所以普通字符串不能用来生成 `tool.result.ok`、机械成功率或失败签名；即使 stdout 含有“Process exited with code 2”，也不会信任它。
+若其它宿主明确给出结构化 `exit_code`，适配器才会上报该状态；当前 CLI 的路径仍用无成败断言的 query / read。
+这也意味着它不能提供与 DSH 完全相同的失败配对统计。没有 workflow / goal 事件、工作区快照或压缩摘要采集能力。
+
+### 配置
+
+| 环境变量 | 默认 / 用途 |
+|---|---|
+| CROWDMEMORY_ENDPOINT_FILE | `~/.crowdmemory/state/endpoint.json`，必须为可信绝对路径 |
+| CROWDMEMORY_PROJECT | 默认工作目录名；推荐显式使用稳定仓库名 |
+| CROWDMEMORY_PROFILE | session-default |
+| CROWDMEMORY_CODEX_STATE | 私有路由状态目录；默认 `$CODEX_HOME/crowdmemory/sessions`（未设置 CODEX_HOME 则为 `~/.codex/crowdmemory/sessions`），hooks 与 MCP 共用 |
+| CROWDMEMORY_INJECT | `0` / `false` / `off` / `no` 关闭自动投递，记忆工具仍可使用 |
+| CROWDMEMORY_NOTES | 同上，关闭 memory_note |
+| CROWDMEMORY_DEBUG | `1` 只报告 hook 降级，不打印输入或令牌 |
+
+MCP 通过 `.mcp.json` 的相对 `cwd` 启动，不能套用 OpenClaude 的 `${PLUGIN_ROOT}` 参数插值；配置变量通过显式 `env_vars` 传递。
+会话状态使用 0700 目录、0600 文件、锁和原子替换。会话字段是本机合作式路由，不是对恶意同用户进程的强认证。
+project 也是相关性约定，不是多租户安全边界。Runtime 失联时 hooks 无输出并退出 0，工具返回不可用；笔记失败需调用方重试。
+
+## 开发与验证
+
+在仓库本包目录安装开发依赖；源码验证也可用 `npm pack` 打包，再解包交给下面的 CLI 测试。
+
+```bash
+pnpm install --frozen-lockfile
+pnpm typecheck
+pnpm test
+pnpm build
+node e2e/run.mjs
+CROWDMEMORY_E2E_PLUGIN_DIR=/absolute/unpacked/package node e2e/run.mjs
+# 已有测试专用 Runtime 时，额外运行真实服务测试：
+CROWDMEMORY_TEST_REAL_ENDPOINT_FILE=/absolute/runtime/state/endpoint.json pnpm test
+```
+
+单测覆盖合同、跨进程绑定、字段保留、父子会话、降级和 stdout 无状态场景。真实 Runtime 测试需显式给测试端点，否则跳过。
+CLI e2e 使用真实 Codex、隔离 CODEX_HOME、本地脚本化 Responses 服务和假 Runtime，验证打包安装、写笔记、下一会话召回与读取。
+仅这个受控离线测试会绕过 hook 信任及审批；它不使用真实模型、服务密钥或生产工作区，也不代表设备或生产模型验收。
+
+公共源码改动请在 `../memory-adapter-core` 修改并执行 `npm run update`，不要直接编辑 `src/core/`、`contract/` 或测试夹具副本。
+官方合同依据：[Hooks](https://developers.openai.com/codex/hooks/)、[插件打包](https://developers.openai.com/plugins/build/plugins)。

package/contract/SNAPSHOT.json

@@ -0,0 +1,17 @@
+{
+  "source": "crowdmemory-contracts",
+  "files": {
+    "error-signature-vectors.json": {
+      "source_path": "fixtures/agent/error-signature-vectors.json",
+      "sha256": "31be508ed2baec0051ef4cd6a2292e39d12c896df76158f9899770f3fefe925d"
+    },
+    "event-id-vectors.json": {
+      "source_path": "fixtures/agent/event-id-vectors.json",
+      "sha256": "c7f016a2251a9d53eb14346fb9823a8c53fee8c1935db06a1ed2b3ac5d5d4b7b"
+    },
+    "memory-agent-ingress-v1.schema.json": {
+      "source_path": "schemas/agent/memory-agent-ingress-v1.schema.json",
+      "sha256": "a0a1c79c0aaedeb076df7e15b069ad8d235bffe3477821e2c3e502049e43cd33"
+    }
+  }
+}

package/contract/error-signature-vectors.json

@@ -0,0 +1,143 @@
+{
+  "schema": "memory-agent-error-signature-vectors/v1",
+  "algorithm": {
+    "id": "crowdmemory-error-signature/v1",
+    "steps": [
+      "split input into lines with line_split",
+      "take the first line that is non-empty after stripping whitespace (leading and trailing runs of the whitespace class); none -> normalized \"\" and signature null",
+      "replace every match of path with \"<path>\"",
+      "replace every match of hex with \"#\"",
+      "replace every match of digits with \"#\"",
+      "strip whitespace from both ends",
+      "signature = \"sha256:\" + lowercase hex sha256 of the UTF-8 bytes of normalized"
+    ],
+    "line_split": "\\r\\n|\\r|\\n",
+    "whitespace": "[ \\t\\u000b\\u000c\\u00a0\\u3000\\ufeff]",
+    "path": "(?<![A-Za-z0-9_.~/\\-])(?:~/[^ \\t\\u000b\\u000c\\u00a0\\u3000\\ufeff'\"`:;,()\\[\\]{}<>|\\uff0c\\u3002\\uff1a\\uff1b\\u3001\\uff08\\uff09\\u3010\\u3011\\u300c\\u300d\\u300a\\u300b\\uff01\\uff1f]*|/[^ \\t\\u000b\\u000c\\u00a0\\u3000\\ufeff'\"`:;,()\\[\\]{}<>|\\uff0c\\u3002\\uff1a\\uff1b\\u3001\\uff08\\uff09\\u3010\\u3011\\u300c\\u300d\\u300a\\u300b\\uff01\\uff1f]+)",
+    "hex": "0[xX][0-9a-fA-F]+",
+    "digits": "[0-9]+",
+    "regex_flags": "none (JavaScript: compile with flags 'g' or 'gu'; results are identical)"
+  },
+  "vectors": [
+    {
+      "name": "ac01-ld-undefined-symbol",
+      "input": "ld: undefined symbol deflate",
+      "normalized": "ld: undefined symbol deflate",
+      "signature": "sha256:d3edaf502f6fc71218f3317d4b9322145eda80702954373c9cf7cc404c90e467"
+    },
+    {
+      "name": "lld-undefined-with-path",
+      "input": "ld.lld: error: undefined symbol: deflate\n>>> referenced by /home/alice/zlib-1.3.1/build/gzlib.c:252",
+      "normalized": "ld.lld: error: undefined symbol: deflate",
+      "signature": "sha256:a060d3150de6839d0de5636a0a4cf3515482bcef7750af5301852def9a148180"
+    },
+    {
+      "name": "compiler-path-line-col",
+      "input": "/Users/bob/src/proj/a.c:301:17: error: 'foo' undeclared (first use in this function)",
+      "normalized": "<path>:#:#: error: 'foo' undeclared (first use in this function)",
+      "signature": "sha256:5a52476f0a3c57631f74f7657fa0d4bba6304f632f90be00350ec50cd362b9fb"
+    },
+    {
+      "name": "home-path",
+      "input": "fatal: cannot open ~/work/proj/CMakeLists.txt: No such file or directory",
+      "normalized": "fatal: cannot open <path>: No such file or directory",
+      "signature": "sha256:7f822aa33d3bdf37666d178d551efb91205654362c52dd9dd401cc2e68516760"
+    },
+    {
+      "name": "leading-blank-lines-crlf",
+      "input": "\r\n   \r\n\tmake[2]: *** [Makefile:1234: all] Error 2\r\nmake: *** [all] Error 2",
+      "normalized": "make[#]: *** [Makefile:#: all] Error #",
+      "signature": "sha256:27cf2b48c8f4a25c5bbed2db28f81db741d7cf2414a2a4346e9025a3049501a8"
+    },
+    {
+      "name": "hex-address",
+      "input": "Segmentation fault at address 0x7ffe3a1f (pid 4242)",
+      "normalized": "Segmentation fault at address # (pid #)",
+      "signature": "sha256:9ec14b3f4c101c85b0bc279b614293e1c3ba41b62d5543fe3329ba83a7b515ac"
+    },
+    {
+      "name": "hex-uppercase-and-digits",
+      "input": "error 0XDEADBEEF in module v2.10.3",
+      "normalized": "error # in module v#.#.#",
+      "signature": "sha256:7fbfe4dc0c5f52c837d4c8e29408dfafd2f4ff0081fc784971768b9992e2246d"
+    },
+    {
+      "name": "cjk-message",
+      "input": "错误：找不到头文件 /opt/sdk/include/zlib.h，第 12 行",
+      "normalized": "错误：找不到头文件 <path>，第 # 行",
+      "signature": "sha256:69bca71d62c373d682636ed3e631c07ac3a5cc29b28369bbdb24af334a0a7f7d"
+    },
+    {
+      "name": "cjk-fullwidth-space",
+      "input": "　　编译失败：退出码 127　",
+      "normalized": "编译失败：退出码 #",
+      "signature": "sha256:6373e60cd9816ed277a49259951f96f29e4b3360300e820b20f504c881020d35"
+    },
+    {
+      "name": "windows-path",
+      "input": "C:\\Users\\dev\\lib2\\zlib1.dll not found (code 126)",
+      "normalized": "C:\\Users\\dev\\lib#\\zlib#.dll not found (code #)",
+      "signature": "sha256:ec9f0e9e955b0b1f1acce5221ece95a3679ff1a40a5cbd83f7edaafaf58ec212"
+    },
+    {
+      "name": "windows-forward-slash",
+      "input": "LINK : fatal error LNK1104: cannot open file 'C:/Program Files/zlib/lib/zlib.lib'",
+      "normalized": "LINK : fatal error LNK#: cannot open file 'C:<path> Files/zlib/lib/zlib.lib'",
+      "signature": "sha256:60d314e0fd9f7301500aa4fdcd86ce4bce3e3b3ffedd7cbe385f4c53ea2e3e69"
+    },
+    {
+      "name": "relative-path-kept",
+      "input": "./configure: line 88: ./build/run.sh: Permission denied",
+      "normalized": "./configure: line #: ./build/run.sh: Permission denied",
+      "signature": "sha256:4492dc461c7153c04caf76cb8a06a5308618851424d41f47eb083408fb42461b"
+    },
+    {
+      "name": "url",
+      "input": "curl: (6) Could not resolve host: https://example.com/pkg/v1.2.tar.gz",
+      "normalized": "curl: (#) Could not resolve host: https:<path>",
+      "signature": "sha256:f4f70a34a840eb4bfd12ed167d0ce870e10edcb70e66de6a0cc1e50b1a2c7450"
+    },
+    {
+      "name": "quoted-path",
+      "input": "No such file: \"/tmp/build-123/out.o\"",
+      "normalized": "No such file: \"<path>\"",
+      "signature": "sha256:b96acfdf62ae2c4f9d1f13af9162a8baf99d2d81d85e2ee2402eda490737cda9"
+    },
+    {
+      "name": "assignment-path",
+      "input": "invalid value --prefix=/usr/local/opt/zlib@1.3",
+      "normalized": "invalid value --prefix=<path>",
+      "signature": "sha256:c22ead0b9c649f9d52595a955774ecd684c55e75bee45e9d1a9da28397c7ca7f"
+    },
+    {
+      "name": "python-traceback-first-line",
+      "input": "Traceback (most recent call last):\n  File \"/usr/lib/python3.11/runpy.py\", line 198, in _run_module_as_main",
+      "normalized": "Traceback (most recent call last):",
+      "signature": "sha256:5dd94ced5a2afb4af3a0a9521dc8f9306236b23b01882c52a80e482ae00be37f"
+    },
+    {
+      "name": "cr-only-lines",
+      "input": "\rwarning: 3 issues\rsecond",
+      "normalized": "warning: # issues",
+      "signature": "sha256:9e4bf262457ac21ae57deaaef52771269d17839818015ed6b790f39b16c9d17e"
+    },
+    {
+      "name": "symbol-with-digits",
+      "input": "undefined reference to `_PyLong_One'",
+      "normalized": "undefined reference to `_PyLong_One'",
+      "signature": "sha256:e48e8db4b536f113bfafe096ddbfc704f24ed7d8fd3cd8363d38c1626883a9ba"
+    },
+    {
+      "name": "empty",
+      "input": "",
+      "normalized": "",
+      "signature": null
+    },
+    {
+      "name": "whitespace-only",
+      "input": " \t\r\n　\n",
+      "normalized": "",
+      "signature": null
+    }
+  ]
+}

package/contract/event-id-vectors.json

@@ -0,0 +1,128 @@
+{
+  "algorithm": "crowdmemory-event-id/v1",
+  "description": "Cross-language vectors for the ingress event_id (memory-agent-ingress/v1). occurred_at = the client's clock truncated to whole seconds, UTC, 'Z'. canonical = canonical JSON of the envelope without event_id: object keys sorted by UTF-16 code unit, no insignificant whitespace, strings as JSON.stringify (only \" \\ and controls < U+0020 escaped, \\b \\f \\n \\r \\t short forms, other controls and lone surrogates as lowercase \\uXXXX), numbers as ECMAScript Number::toString (1.0 -> 1, -0 -> 0, 1e-7, 1e+21; integers only within +-2^53). event_id = 'sha256:' + hex(sha256(UTF-8(canonical + '\\n' + native_key))), lone surrogates encoded as U+FFFD. Generated by the TS adapter client (src/client.ts); the Python AgentIngressClient must reproduce every vector.",
+  "vectors": [
+    {
+      "name": "session-start-business",
+      "adapter_id": "example-pipeline",
+      "session_ref": "pipe-0001",
+      "parent_ref": null,
+      "now": "2026-10-20T08:00:00.000Z",
+      "occurred_at": "2026-10-20T08:00:00Z",
+      "kind": "session.start",
+      "payload": {
+        "project": "pipeline-demo",
+        "profile_ref": "example-pipeline",
+        "capabilities": [
+          "session_binding",
+          "step_injection",
+          "tool_capture",
+          "note_tool",
+          "query_tools",
+          "workflow_events"
+        ],
+        "dimensions": {
+          "platform": "linux-x86_64",
+          "toolchain": "gcc-13"
+        }
+      },
+      "native_key": "session.start",
+      "canonical": "{\"adapter_id\":\"example-pipeline\",\"kind\":\"session.start\",\"occurred_at\":\"2026-10-20T08:00:00Z\",\"parent_ref\":null,\"payload\":{\"capabilities\":[\"session_binding\",\"step_injection\",\"tool_capture\",\"note_tool\",\"query_tools\",\"workflow_events\"],\"dimensions\":{\"platform\":\"linux-x86_64\",\"toolchain\":\"gcc-13\"},\"profile_ref\":\"example-pipeline\",\"project\":\"pipeline-demo\"},\"session_ref\":\"pipe-0001\"}",
+      "event_id": "sha256:5f279b6cd45e51d6ee10357f01358b0878857beffc9eea4bc25704df4851a240"
+    },
+    {
+      "name": "tool-result-unicode-and-key-order",
+      "adapter_id": "dsh",
+      "session_ref": "dsh-session-0001",
+      "parent_ref": "dsh-parent-0001",
+      "now": "2026-10-20T08:00:01.999Z",
+      "occurred_at": "2026-10-20T08:00:01Z",
+      "kind": "tool.result",
+      "payload": {
+        "tool_name": "bash",
+        "session_handle": "ash_0123456789abcdef0123456789abcdef",
+        "ok": false,
+        "exit_code": 2,
+        "error_tail": "\u9519\u8bef\uff1a\u627e\u4e0d\u5230 <path>/zlib.h\ttab \"quoted\" \\ back\u0001ctl\u2028ls \ud83d\ude00 emoji",
+        "symbols": [
+          "zlib.h",
+          "deflate"
+        ],
+        "z": {
+          "\uffff": 1,
+          "\ud83d\ude00": 2,
+          "B": 3,
+          "a": 4,
+          "": 5
+        }
+      },
+      "native_key": "call_\u00fc_01",
+      "canonical": "{\"adapter_id\":\"dsh\",\"kind\":\"tool.result\",\"occurred_at\":\"2026-10-20T08:00:01Z\",\"parent_ref\":\"dsh-parent-0001\",\"payload\":{\"error_tail\":\"\u9519\u8bef\uff1a\u627e\u4e0d\u5230 <path>/zlib.h\\ttab \\\"quoted\\\" \\\\ back\\u0001ctl\u2028ls \ud83d\ude00 emoji\",\"exit_code\":2,\"ok\":false,\"session_handle\":\"ash_0123456789abcdef0123456789abcdef\",\"symbols\":[\"zlib.h\",\"deflate\"],\"tool_name\":\"bash\",\"z\":{\"\":5,\"B\":3,\"a\":4,\"\ud83d\ude00\":2,\"\uffff\":1}},\"session_ref\":\"dsh-session-0001\"}",
+      "event_id": "sha256:a2c24ea5485d87c8677f7fcd76d26a6341fb7fcee8511976d8343cb4e5e8e7dd"
+    },
+    {
+      "name": "numbers",
+      "adapter_id": "example-pipeline",
+      "session_ref": "pipe-0002",
+      "parent_ref": null,
+      "now": "2026-10-20T08:00:02Z",
+      "occurred_at": "2026-10-20T08:00:02Z",
+      "kind": "note",
+      "payload": {
+        "n": [
+          0,
+          -0.0,
+          1.0,
+          -1.5,
+          0.1,
+          1e-07,
+          1e-06,
+          1e+16,
+          1e+21,
+          123456789012345680000,
+          2.5e-08,
+          9007199254740991,
+          3.14159,
+          -273.15,
+          100,
+          1.5e+300
+        ],
+        "flags": [
+          true,
+          false,
+          null
+        ],
+        "nested": {
+          "b": [
+            {
+              "y": 1,
+              "x": 2
+            }
+          ],
+          "a": {}
+        },
+        "empty": []
+      },
+      "native_key": "note:1",
+      "canonical": "{\"adapter_id\":\"example-pipeline\",\"kind\":\"note\",\"occurred_at\":\"2026-10-20T08:00:02Z\",\"parent_ref\":null,\"payload\":{\"empty\":[],\"flags\":[true,false,null],\"n\":[0,0,1,-1.5,0.1,1e-7,0.000001,10000000000000000,1e+21,123456789012345680000,2.5e-8,9007199254740991,3.14159,-273.15,100,1.5e+300],\"nested\":{\"a\":{},\"b\":[{\"x\":2,\"y\":1}]}},\"session_ref\":\"pipe-0002\"}",
+      "event_id": "sha256:c3485b5eb60d0e903e9ad7b5729a0ac3f73c117e8348a94e938dc5d4560669d1"
+    },
+    {
+      "name": "lone-surrogate",
+      "adapter_id": "dsh",
+      "session_ref": "dsh-session-0003",
+      "parent_ref": null,
+      "now": "2026-10-20T08:00:03Z",
+      "occurred_at": "2026-10-20T08:00:03Z",
+      "kind": "query",
+      "payload": {
+        "session_handle": "ash_0123456789abcdef0123456789abcdef",
+        "op": "search",
+        "query": "half \ud800 pair"
+      },
+      "native_key": "q:\ud800",
+      "canonical": "{\"adapter_id\":\"dsh\",\"kind\":\"query\",\"occurred_at\":\"2026-10-20T08:00:03Z\",\"parent_ref\":null,\"payload\":{\"op\":\"search\",\"query\":\"half \\ud800 pair\",\"session_handle\":\"ash_0123456789abcdef0123456789abcdef\"},\"session_ref\":\"dsh-session-0003\"}",
+      "event_id": "sha256:c2b337b0b5ad0ee362a9ff5a319ac48a613a6ff090365396093eeb98d98090a1"
+    }
+  ]
+}