pi-rehydra 1.0.3 → 1.0.4

package/README.en.md

@@ -1,83 +1,88 @@
-# pi-rehydra
-
-Scrub detected secrets from Pi conversations before the main LLM request.
-
-[中文](./README.md)
-
-This extension intercepts the conversation between [Pi](https://pi.dev) and the LLM. Secrets from your `.env` files are replaced with placeholders before they leave your machine, and transparently restored before any tool (shell commands, file writes, etc.) executes locally; a placeholder that cannot be restored blocks that tool call.
-
-It uses Pi's `ExtensionAPI` events: `context_with_system`, `tool_call`, `tool_result`, `message_end`, and `session_start` / `session_shutdown`.
-
-Detection and rehydration are local. The model only sees placeholders; your tools always see real values.
-
-## Install
-
-```bash
-pi install npm:pi-rehydra
-```
-
-Pi writes the package entry to `~/.pi/agent/settings.json`. Edit that file to add extension options:
-
-```json
-{
-  "packages": [
-    {
-      "source": "npm:pi-rehydra"
-    }
-  ],
-  "rehydra": {
-    "envFiles": [".env", ".env.local"],
-    "redactValues": ["sk-live-abc123..."],
-    "allowLiteralTagsIn": ["write", "edit"]
-  }
-}
-```
-
-Every key under `rehydra` is an extension option: `envFiles`, `redactValues`, `minValueLength`, `disableTypes`, `locale`, `vcsIdentities`, `policy`, `anonymizer`, `tagFormat`. `envFiles` defaults to `["**/.env*"]`, skipping `node_modules`, `.git`, and symlinks.
-
-`allowLiteralTagsIn` defaults to an empty array (always block). Tools listed here — typically `write` and `edit` — keep an **unresolvable** literal tag in their arguments instead of aborting, so you can write documentation or tests that intentionally show tag examples. Every allowed occurrence is logged (`allowed literal tag in tool args`, tool name and argument path only). Resolvable tags are still restored in every tool.
-
-## How it works
-
-| Event | Effect |
-|---|---|
-| `session_start` | Instantiate the anonymizer, build the session map, parse the `rehydra` config |
-| `context_with_system` | Anonymize all request messages and inject the rehydra instruction when needed |
-| `tool_call` | Strictly restore PII tags in tool arguments before local execution; an unresolvable tag blocks the call |
-| `tool_result` | Anonymize the completed tool result before it re-enters model context |
-| `message_end` | Rewrite the final assistant message so PII tags are replaced with real values |
-| `session_shutdown` | Dispose of the anonymizer and session registry |
-
-## Masking records and comparison
-
-Once enabled, you can check request by request what was intercepted and what the model actually received:
-
-```json
-{
-  "rehydra": {
-    "record": {
-      "enabled": true,
-      "includeOriginal": true
-    }
-  }
-}
-```
-
-`/rehydra log` lists the last 20 records for the current session, `/rehydra log <id>` shows one record (hit lines plus field-level before/after), `/rehydra log --type EMAIL` filters by type; `/rehydra clear` clears the current session and `/rehydra clear --all` clears everything (both ask for confirmation).
-
-Recording is off by default. When enabled it writes to `~/.pi/agent/rehydra/records/` (directory 0700, files 0600), trimmed by both a 7-day and a 32 MiB cap, with 256 KiB per record for comparisons. **With `includeOriginal` set to true, real values are written to local disk**; set it to false to keep only the type, detector, placeholder, length and offsets. Terminal control characters are escaped when displayed, and record text is never fed back into model context.
-
-Any recording failure (unwritable directory, symlink, half-written line) only produces a warning and never affects masking or the request.
-
-## Limitations
-- Tool-argument rehydration is strict: when a tag is absent from this session's map (or the map is missing, or decryption fails), the tool call is blocked rather than run with `<PII .../>` as a real value. A placeholder can only be restored from the same session's map; the default map is in memory, so tags from before a process restart cannot be restored.
-
-- Model calls that bypass these hooks (rare, e.g. user-initiated notes) are not intercepted.
-- `URL`, `IP_ADDRESS`, `BIC_SWIFT`, `POSTAL_CODE` and `DATE` are disabled by default: recognizers that fire on shape alone misfire badly in code and documents. Restore them with `disableTypes: ["URL", "IP_ADDRESS"]`; a bank identifier still needs a full banking context word nearby.
-- Only the values of sensitive fields in an `.env` file enter the global known-value set; project names and ports are not replaced later in the text. Explicitly configured `redactValues` are not affected by that filter.
-- Collection fields in `policy` may be arrays and thresholds plain objects; an invalid field type fails startup with the field name instead of silently dropping the protection rule.
-- This extension cannot guarantee that title or compaction summaries stay sanitized — disable title agents if you need titles to be human-readable.
-
-## License
-
+# pi-rehydra
+
+Scrub detected secrets from Pi conversations before the main LLM request.
+
+[中文](./README.md)
+
+This extension intercepts the conversation between [Pi](https://pi.dev) and the LLM. Secrets from your `.env` files are replaced with placeholders before they leave your machine, and transparently restored before any tool (shell commands, file writes, etc.) executes locally; a placeholder that cannot be restored blocks that tool call.
+
+It uses Pi's `ExtensionAPI` events: `context_with_system`, `tool_call`, `tool_result`, `message_end`, and `session_start` / `session_shutdown`.
+
+Detection and rehydration are local. The model only sees placeholders; your tools always see real values.
+
+## Install
+
+```bash
+pi install npm:pi-rehydra
+```
+
+Pi writes the package entry to `~/.pi/agent/settings.json`. Edit that file to add extension options:
+
+```json
+{
+  "packages": [
+    {
+      "source": "npm:pi-rehydra"
+    }
+  ],
+  "rehydra": {
+    "envFiles": [".env", ".env.local"],
+    "redactValues": ["sk-live-abc123..."],
+    "allowLiteralTagsIn": ["write", "edit"]
+  }
+}
+```
+
+Every key under `rehydra` is an extension option: `envFiles`, `redactValues`, `minValueLength`, `disableTypes`, `locale`, `vcsIdentities`, `policy`, `anonymizer`, `tagFormat`. `envFiles` defaults to `["**/.env*"]`, skipping `node_modules`, `.git`, and symlinks.
+
+`allowLiteralTagsIn` defaults to an empty array (always block). Tools listed here — typically `write` and `edit` — keep an **unresolvable** literal tag in their arguments instead of aborting, so you can write documentation or tests that intentionally show tag examples. Every allowed occurrence is logged (`allowed literal tag in tool args`, tool name and argument path only). Resolvable tags are still restored in every tool.
+
+## How it works
+
+| Event | Effect |
+|---|---|
+| `session_start` | Instantiate the anonymizer, build the session map, parse the `rehydra` config |
+| `context_with_system` | Anonymize all request messages and inject the rehydra instruction when needed |
+| `tool_call` | Strictly restore PII tags in tool arguments before local execution; an unresolvable tag blocks the call |
+| `tool_result` | Anonymize the completed tool result before it re-enters model context |
+| `message_end` | Rewrite the final assistant message so PII tags are replaced with real values |
+| `session_shutdown` | Dispose of the anonymizer and session registry |
+
+Masked message roles: `user`, `assistant`, `toolResult`, `system` (its `content` and prompt sections, except the tool declarations section), `bashExecution` (command and output), `custom`, `branchSummary`, and `compactionSummary` — exactly the roles Pi turns into model input. When the current request replaced anything, the placeholder guidance is injected as its own prompt section, so the model treats placeholders as opaque pass-through values.
+
+On failure: an uninitialized extension blocks tool execution. A single masking failure does not abort the request — Pi swallows handler errors and sends the unmasked content anyway, so the extension catches them and logs a warning carrying only the event name and reason, never the content.
+
+## Masking records and comparison
+
+Once enabled, you can check request by request what was intercepted and what the model actually received:
+
+```json
+{
+  "rehydra": {
+    "record": {
+      "enabled": true,
+      "includeOriginal": true
+    }
+  }
+}
+```
+
+`/rehydra log` lists the last 20 records for the current session, `/rehydra log <id>` shows one record (hit lines plus field-level before/after), `/rehydra log --type EMAIL` filters by type; `/rehydra clear` clears the current session and `/rehydra clear --all` clears everything (both ask for confirmation).
+
+Recording is off by default. When enabled it writes to `~/.pi/agent/rehydra/records/` (directory 0700, files 0600), trimmed by both a 7-day and a 32 MiB cap, with 256 KiB per record for comparisons. **With `includeOriginal` set to true, real values are written to local disk**; set it to false to keep only the type, detector, placeholder, length and offsets. Terminal control characters are escaped when displayed, and record text is never fed back into model context.
+
+Any recording failure (unwritable directory, symlink, half-written line) only produces a warning and never affects masking or the request.
+
+## Limitations
+- Tool-argument rehydration is strict: when a tag is absent from this session's map (or the map is missing, or decryption fails), the tool call is blocked rather than run with `<PII .../>` as a real value. A placeholder can only be restored from the same session's map; the default map is in memory, so tags from before a process restart cannot be restored.
+
+- Session maps are cached in-process to avoid repeated decryption. The cache is shared per storage instance and session id, so every session instance on the same storage sees the same map, and a streaming save invalidates it. Only another process, or a different storage instance over the same underlying data, can write a map this process's cache will not notice.
+- Model calls that bypass these hooks (rare, e.g. user-initiated notes) are not intercepted.
+- `URL`, `IP_ADDRESS`, `BIC_SWIFT`, `POSTAL_CODE` and `DATE` are disabled by default: recognizers that fire on shape alone misfire badly in code and documents. Restore them with `disableTypes: ["URL", "IP_ADDRESS"]`; a bank identifier still needs a full banking context word nearby.
+- Only the values of sensitive fields in an `.env` file enter the global known-value set; project names and ports are not replaced later in the text. Explicitly configured `redactValues` are not affected by that filter.
+- Collection fields in `policy` may be arrays and thresholds plain objects; an invalid field type fails startup with the field name instead of silently dropping the protection rule.
+- This extension cannot guarantee that title or compaction summaries stay sanitized — disable title agents if you need titles to be human-readable.
+
+## License
+
 MIT

package/README.md

@@ -1,83 +1,86 @@
-# pi-rehydra
-
-在主 LLM 请求发出之前，脱敏 Pi 对话中检测到的密钥。
-
-[English](./README.en.md)
-
-这个扩展拦截 [Pi](https://pi.dev) 与 LLM 之间的对话。你的 `.env` 文件中的密钥在离开本机前被替换为占位符，并在工具（shell 命令、文件写入等）在本地执行前透明还原；无法还原的占位符会阻止该次工具调用。
-
-它依赖 Pi 的 `ExtensionAPI`：`context_with_system`、`tool_call`、`tool_result`、`message_end`、`session_start` / `session_shutdown`。
-
-脱敏和还原都在本地进行；模型只用占位符推理，工具始终拿到真实值。
-
-## 安装
-
-```bash
-pi install npm:pi-rehydra
-```
-
-Pi 会在 `~/.pi/agent/settings.json` 写入包声明。然后编辑该文件添加扩展配置：
-
-```json
-{
-  "packages": [
-    {
-      "source": "npm:pi-rehydra"
-    }
-  ],
-  "rehydra": {
-    "envFiles": [".env", ".env.local"],
-    "redactValues": ["sk-live-abc123..."],
-    "allowLiteralTagsIn": ["write", "edit"]
-  }
-}
-```
-
-`rehydra` 键的所有字段都是扩展配置项：`envFiles`、`redactValues`、`minValueLength`、`disableTypes`、`locale`、`vcsIdentities`、`policy`、`anonymizer`、`tagFormat`。`envFiles` 默认是 `["**/.env*"]`，会跳过 `node_modules`、`.git` 和符号链接。
-
-`allowLiteralTagsIn` 默认是空数组（一律阻断）。列进这个数组的工具（通常是 `write`、`edit`）在参数里出现**无法还原**的字面标签时不再阻断，而是原样保留——用于写文档或测试时故意写标签示例。放行会在日志里留痕（`allowed literal tag in tool args`，只带工具名与参数路径）；能还原的标签在任何工具里都照常还原。
-
-## 工作原理
-
-| 钩子 | 作用 |
-|---|---|
-| `session_start` | 实例化匿名器、装配会话映射、解析 `rehydra` 配置 |
-| `context_with_system` | 匿名化模型请求前的所有消息，并按需追加 rehydra 指令 |
-| `tool_call` | 在工具执行前严格还原工具入参中的 PII 标签；任一标签无法还原即阻断该次调用 |
-| `tool_result` | 在结果返回给模型前脱敏真实 PII |
-| `message_end` | 改写最终回答的文本块，把 PII 标签还原为真实值 |
-| `session_shutdown` | 释放匿名器与会话注册表 |
-
-## 脱敏记录与对照
-
-开启后可以逐请求核对"哪些内容被拦截、模型实际收到了什么"：
-
-```json
-{
-  "rehydra": {
-    "record": {
-      "enabled": true,
-      "includeOriginal": true
-    }
-  }
-}
-```
-
-`/rehydra log` 列出当前会话最近 20 条记录，`/rehydra log <id>` 看单条详情（命中行 + 字段级 before/after），`/rehydra log --type EMAIL` 按类型筛选；`/rehydra clear` 清当前会话，`/rehydra clear --all` 清全部（都要确认）。
-
-记录默认关闭。开启后写入 `~/.pi/agent/rehydra/records/`（目录 0700、文件 0600），按 7 天与 32 MiB 双上限裁剪，单条记录对照上限 256 KiB。**`includeOriginal` 为 true 时真实值会写到本地磁盘**；不需要时设成 `false`，记录只保留类型、检测器、占位符、长度与偏移。记录里出现的终端控制字符在展示时会转义，原文不会回填到模型上下文。
-
-记录层任何失败（目录不可写、符号链接、半行文件）都只告警，不影响脱敏与请求。
-
-## 限制
-- 工具入参还原是严格的：标签不在本次会话映射中（或映射缺失、解密失败）时，该次工具调用会被阻止，不会把 `<PII .../>` 当作真实值执行。占位符只能由同一条会话的映射还原；默认使用内存映射，进程重启后旧标签无法还原。
-
-- 不会拦截用户在 UI 里粘贴的、且未走这些 hook 的模型调用。
-- 默认禁用 `URL`、`IP_ADDRESS`、`BIC_SWIFT`、`POSTAL_CODE`、`DATE`；只靠形状就能命中的识别器在代码与文档里误报率高。需要它们时把 `disableTypes` 写成 `["URL", "IP_ADDRESS"]` 即可恢复。即便恢复，银行标识码仍要求附近出现完整的银行语境词。
-- `.env` 里只有敏感字段的值会进入全局已知值集合：项目名、端口这类普通配置值不会被替换。显式配置的 `redactValues` 不受这条筛选影响。
-- `policy` 的集合类字段可写成数组、阈值可写成对象；字段类型不合法时扩展启动报错并指出字段名，不会静默丢掉保护规则。
-- Pi 扩展无法保证消息标题（title）与元数据走相同的 hook，因此这些字段仍可能包含占位符。建议在脱敏时启用完整的 PII 脱敏策略。
-
-## License
-
+# pi-rehydra
+
+在主 LLM 请求发出之前，脱敏 Pi 对话中检测到的密钥。
+
+[English](./README.en.md)
+
+这个扩展拦截 [Pi](https://pi.dev) 与 LLM 之间的对话。你的 `.env` 文件中的密钥在离开本机前被替换为占位符，并在工具（shell 命令、文件写入等）在本地执行前透明还原；无法还原的占位符会阻止该次工具调用。
+
+它依赖 Pi 的 `ExtensionAPI`：`context_with_system`、`tool_call`、`tool_result`、`message_end`、`session_start` / `session_shutdown`。
+
+脱敏和还原都在本地进行；模型只用占位符推理，工具始终拿到真实值。
+
+## 安装
+
+```bash
+pi install npm:pi-rehydra
+```
+
+Pi 会在 `~/.pi/agent/settings.json` 写入包声明。然后编辑该文件添加扩展配置：
+
+```json
+{
+  "packages": [
+    {
+      "source": "npm:pi-rehydra"
+    }
+  ],
+  "rehydra": {
+    "envFiles": [".env", ".env.local"],
+    "redactValues": ["sk-live-abc123..."],
+    "allowLiteralTagsIn": ["write", "edit"]
+  }
+}
+```
+
+`rehydra` 键的所有字段都是扩展配置项：`envFiles`、`redactValues`、`minValueLength`、`disableTypes`、`locale`、`vcsIdentities`、`policy`、`anonymizer`、`tagFormat`。`envFiles` 默认是 `["**/.env*"]`，会跳过 `node_modules`、`.git` 和符号链接。
+
+`allowLiteralTagsIn` 默认是空数组（一律阻断）。列进这个数组的工具（通常是 `write`、`edit`）在参数里出现**无法还原**的字面标签时不再阻断，而是原样保留——用于写文档或测试时故意写标签示例。放行会在日志里留痕（`allowed literal tag in tool args`，只带工具名与参数路径）；能还原的标签在任何工具里都照常还原。
+
+## 工作原理
+
+| 钩子 | 作用 |
+|---|---|
+| `session_start` | 实例化匿名器、装配会话映射、解析 `rehydra` 配置 |
+| `context_with_system` | 匿名化模型请求前的所有消息，并在本轮有替换时追加占位符说明 |
+| `tool_call` | 在工具执行前严格还原工具入参中的 PII 标签；任一标签无法还原即阻断该次调用 |
+| `tool_result` | 在结果返回给模型前脱敏真实 PII |
+| `message_end` | 改写最终回答的文本块，把 PII 标签还原为真实值 |
+| `session_shutdown` | 释放匿名器与会话注册表 |
+覆盖的消息角色：`user`、`assistant`、`toolResult`、`system`（其 `content` 与各提示分段，工具声明段除外）、`bashExecution`（命令与输出）、`custom`、`branchSummary` 与 `compactionSummary`——这些正是宿主会转成模型输入的几种。本轮若发生过替换，占位符说明会作为独立提示分段注入，模型因此知道占位符是不可解析的透传值。
+
+失败时的行为：扩展未初始化则阻止工具执行。单次脱敏失败不会中断请求——宿主会吞掉处理器异常并继续发送未脱敏内容，所以扩展自行捕获并写一条告警（只带事件名与原因，不含正文）。
+## 脱敏记录与对照
+
+开启后可以逐请求核对"哪些内容被拦截、模型实际收到了什么"：
+
+```json
+{
+  "rehydra": {
+    "record": {
+      "enabled": true,
+      "includeOriginal": true
+    }
+  }
+}
+```
+
+`/rehydra log` 列出当前会话最近 20 条记录，`/rehydra log <id>` 看单条详情（命中行 + 字段级 before/after），`/rehydra log --type EMAIL` 按类型筛选；`/rehydra clear` 清当前会话，`/rehydra clear --all` 清全部（都要确认）。
+
+记录默认关闭。开启后写入 `~/.pi/agent/rehydra/records/`（目录 0700、文件 0600），按 7 天与 32 MiB 双上限裁剪，单条记录对照上限 256 KiB。**`includeOriginal` 为 true 时真实值会写到本地磁盘**；不需要时设成 `false`，记录只保留类型、检测器、占位符、长度与偏移。记录里出现的终端控制字符在展示时会转义，原文不会回填到模型上下文。
+
+记录层任何失败（目录不可写、符号链接、半行文件）都只告警，不影响脱敏与请求。
+
+## 限制
+- 工具入参还原是严格的：标签不在本次会话映射中（或映射缺失、解密失败）时，该次工具调用会被阻止，不会把 `<PII .../>` 当作真实值执行。占位符只能由同一条会话的映射还原；默认使用内存映射，进程重启后旧标签无法还原。
+
+- 会话映射在进程内缓存以避免重复解密。缓存按「存储实例 + 会话 ID」共享，因此同一存储上的多个会话实例看到的是一致的映射；流式脱敏写盘后也会让缓存失效。仅当**另一个进程**，或另一个指向同一份底层数据的存储实例改写时，本进程缓存不会失效。
+- 不会拦截用户在 UI 里粘贴的、且未走这些 hook 的模型调用。
+- 默认禁用 `URL`、`IP_ADDRESS`、`BIC_SWIFT`、`POSTAL_CODE`、`DATE`；只靠形状就能命中的识别器在代码与文档里误报率高。需要它们时把 `disableTypes` 写成 `["URL", "IP_ADDRESS"]` 即可恢复。即便恢复，银行标识码仍要求附近出现完整的银行语境词。
+- `.env` 里只有敏感字段的值会进入全局已知值集合：项目名、端口这类普通配置值不会被替换。显式配置的 `redactValues` 不受这条筛选影响。
+- `policy` 的集合类字段可写成数组、阈值可写成对象；字段类型不合法时扩展启动报错并指出字段名，不会静默丢掉保护规则。
+- Pi 扩展无法保证消息标题（title）与元数据走相同的 hook，因此这些字段仍可能包含占位符。建议在脱敏时启用完整的 PII 脱敏策略。
+
+## License
+
 MIT

package/dist/pi-extension/extension.d.ts

@@ -7,12 +7,14 @@
  * - `tool_call` 在工具执行前严格还原入参标签；还原不全即阻断该次调用；
  * - `tool_result` 在结果回填给模型前就地脱敏真实 PII；
  * - `message_end` 改写最终 assistant 文本，把 PII 标签还原为真值；
- * - `session_start` / `session_shutdown` 管理会话与匿名器生命周期；
- * - `input` / `user_bash` 在源头做最低限度的脱敏，避免走特殊路径的 PII 漏出。
+ * - `session_start` / `session_shutdown` 管理会话与匿名器生命周期。
  *
  * 设计目标：
  * - 复用 {@link scrubCore} 递归处理消息树；
- * - 失败关闭：任何 scrub 异常都向上抛出，Pi 会停在该请求而不是泄漏；
+ * - 覆盖宿主会转成模型输入的全部消息角色（user / assistant / toolResult /
+ *   system / bashExecution / custom / 两类摘要）；
+ * - 失败语义：宿主会吞掉处理器异常并继续用未脱敏内容发请求，因此脱敏异常
+ *   在扩展内自行捕获并告警；工具执行路径则失败关闭（阻断该次调用）；
  * - 资源释放：`session_shutdown` 幂等释放 session 注册表与匿名器；
  * - 暴露 `/rehydra` 命令，便于用户在交互模式快速查看当前配置。
  */

package/dist/pi-extension/extension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../src/pi-extension/extension.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAGV,YAAY,EAOb,MAAM,iBAAiB,CAAC;AAwjBzB,yBAAyB;AACzB,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,wBAAwB;IACxB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAoU/D"}
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../src/pi-extension/extension.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAGV,YAAY,EAOb,MAAM,iBAAiB,CAAC;AAwvBzB,yBAAyB;AACzB,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,wBAAwB;IACxB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA4W/D"}