pi-cache-stack

pi-cache-stack 是运行在官方 Pi 上的工具发现与 active-tool policy 扩展。它只负责：

1. 最小初始工具集：保留 lazy gateway、默认基础工具和配置中的 alwaysActive 工具。
2. 工具发现：通过 lazy search 或 /lazy search 查找未激活的注册工具。
3. 会话内激活策略：lazy activate 使用 setActiveTools(current + additions) 纯增量地加入工具，并在后续轮次保持。
4. 外部 ownership 保留：externallyManaged 工具由 owning extension 决定是否 active；cache-stack 只保留当前状态，不主动添加，也不允许 lazy 绕过 owner policy。
5. 策略诊断：显示 active tools、请求体大小、disabled/externally-managed 工具、模型策略和官方 fallback 边界。
6. 工具输出边界：在最终工具结果进入模型与会话上下文前，对指定工具执行可配置的 UTF-8 安全截断，并保留完整输出文件。

Prompt cache、session affinity、addedToolNames、additional_tools / tool-search / deferred tool serialization，以及 active tools 对应的 Available tools/Guidelines 都由官方 Pi/provider 负责。本扩展不会修改 system prompt、构建 provider payload，也不会保存或实现 prompt cache。

官方 Pi 与 provider 的边界

• ChatGPT OAuth/OpenAI 的 prompt_cache_key、session affinity 和 native dynamic tool loading 由官方 Pi/provider 处理。
• 支持 native deferred loading 的模型可以由官方 Pi 在工具结果位置加载新增工具定义，并使用 addedToolNames 选择 provider 原生序列化。
• 没有 native deferred loading 的 provider 仍会由官方 Pi 发送当前 active tools。cache-stack 只减少初始和未使用工具的请求体，不承诺激活轮的完整 prompt-cache 命中。
• reset、模型策略变化或 disabled 变化需要移除 active tools 时，会走官方 fallback。此类变更可能重建 system prompt 并使 provider prefix-cache entry 失效。
• getAllTools() 的公共 ToolInfo snapshot 只暴露 promptGuidelines，不暴露 promptSnippet。搜索、激活结果和 /lazy 状态会标记可见的 prompt guidelines，并始终给出保守的通用提示；扩展不会读取私有字段，也不会剥离、冻结或替换这些 metadata。带 prompt metadata 的工具激活可能触发官方 Pi 的 system-prompt rebuild。
• 官方 Pi 根据当前 active tool set 自己生成 Available tools/Guidelines。cache-stack 的 before_agent_start 只做 policy reconcile，不返回自定义 system prompt，也不注入完整 inactive-tool catalog；inactive tools 通过 lazy({}) 状态和 lazy({ search: "..." }) 发现。

lazy 不是权限隔离。它只控制当前 Pi session 的 active tool 集合，模型可以搜索并激活未被 disabled 且未声明为 externallyManaged 的注册工具。

安装

推荐通过官方 Pi package manager 安装：

pi install npm:pi-cache-stack

固定版本：

pi install npm:pi-cache-stack@0.5.0

管理命令：

pi update npm:pi-cache-stack
pi remove npm:pi-cache-stack

如果之前通过 Git 或本地目录加载过同一扩展，应先移除旧来源，避免重复加载。安装或切换后执行 /reload，必要时重启 Pi。

配置

配置文件为 ~/.pi/agent/cache-stack.json。节级对象深合并，数组整体替换，null 视为未设置。配置只描述工具 policy，不配置 provider cache 或请求 payload。

{
  "lazyTools": {
    "enabled": true,
    // 默认 bash/read/write/edit/ls/find/grep 会保留；这里追加工具
    "alwaysActive": [],
    // 注册但不允许进入 active set 或被 lazy activate
    "disabled": [],
    // 由其他扩展决定 active；这里只保留 owner 当前已激活的状态
    "externallyManaged": ["openai_generate_image"],
    // 按模型覆盖 policy；支持 * 和 ? 通配符
    "modelOverrides": {
      "anthropic/claude-haiku-*": {
        "enabled": false
      },
      "openai/gpt-5.6-*": {
        "enabled": true,
        "alwaysActive": ["mcp"],
        "disabled": [],
        "externallyManaged": ["openai_generate_image"]
      }
    }
  },
  "toolOutput": {
    // 只限制最终写入模型/会话上下文的结果，不影响 UI 实时流式显示
    "enabled": true,
    "maxBytes": 20480,
    "maxLines": 2000,
    "tools": ["bash", "read", "grep", "find", "ls"]
  }
}

行为说明：

• enabled: true 时，session 初始 active set 为 lazy gateway、默认基础工具和 alwaysActive 工具；其他已注册工具通过搜索后激活。
• enabled: false 时恢复当前注册表中的完整工具集，并在 resume、tree navigation 和 compaction 后继续保持完整集。disabled 在该模式下不是权限边界。
• alwaysActive 会与默认基础工具合并；disabled 最终优先。
• externallyManaged 是 preserve-only：已由 owner 激活的注册工具会保留，inactive 工具不会被 cache-stack 添加、搜索或 lazy activate，也不会写入 branch activation snapshot。关闭这类工具应使用 owning extension 的配置。
• 同一名称同时出现在 externallyManaged 与 disabled/alwaysActive 时属于 ownership 冲突，/lazy 会明确诊断；cache-stack reconcile 中仍保持现有 disabled 优先和 alwaysActive 主动添加语义。
• modelOverrides 在 model_select 时重新解析。数组整体替换；仍符合策略的 session activation 和当前 active 的 externally-managed 工具会保留，被 disabled、移出注册表或转为其他 ownership 的 cache-owned activation 会被移除，并标记为官方 fallback。
• toolOutput 默认限制 bash/read/grep/find/ls 的最终文本结果为 20KB 或 2000 行。bash 保留尾部，其他默认工具保留头部；发生截断时完整文本会保存到 ~/.pi/pi-cache-stack/tool-output/ 并在结果中给出路径。
• toolOutput.tools 是整体替换的 allowlist；设 enabled: false 可恢复官方 Pi 的原始结果大小。图片块、错误状态、usage 和工具 details 保持不变。
• 工具输出限制发生在 tool_result 边界，因此不会缩短执行中的 UI streaming update，只限制最终进入模型和 session history 的内容。
• 配置错误会 fail-open 到规范化默认值，不阻塞 Pi 启动。

发现、激活与诊断

模型可以调用：

lazy({})
lazy({ search: "web search URL" })
lazy({ activate: ["web_search"] })
lazy({ reset: true })

用户命令：

/lazy
/lazy search <query>
/lazy activate <name>[,<name>...]
/lazy reset

激活是纯增量操作：扩展读取当前 getActiveTools()，调用 setActiveTools(current + additions)。因此官方 Pi 可以识别新增工具名并决定走 native deferred loading 或 fallback。只有模型调用 lazy({ activate }) 的工具执行路径标为 native-candidate；/lazy activate、model/lifecycle reconcile、reset、disabled/removal 和 branch restore 都是官方 fallback。active set 未变化时标为 no-op，不会重复调用 setActiveTools()。

激活状态通过官方 pi.appendEntry() 写入当前 branch 的 pi-cache-stack.activation-state.v1 custom entry：

{
  "version": 1,
  "activatedTools": ["tool_name"]
}

新 session 从空 activation 开始；resume、fork、session tree navigation 和 successful compaction 从当前 branch 最后一条有效 snapshot 恢复，并过滤 missing、disabled、always-active、externally-managed 工具。相同 snapshot 不会重复追加 entry。旧版本 snapshot 中多余的 catalogHash 字段会被安全忽略，历史 activation state 仍可恢复。

/lazy 状态还会显示：

• 当前 active tools、inactive discoverable tool names 与估算的请求体开销；
• externally-managed 工具的 active/inactive/unregistered 状态及 ownership 冲突；
• 本 session 已激活的 lazy tools；
• 最近一次 active-tool update 是 initial、native-candidate、official fallback 还是 no-op；
• 带 prompt metadata 的工具及其可能的 system-prompt/cache 影响。

开发

npm install --ignore-scripts
npm run typecheck
npm test

测试覆盖配置规范化、最小初始工具集、before_agent_start 不替换 system prompt、purely-additive activation、branch-local session persistence/restore、legacy snapshot 兼容、compaction no-op、prompt metadata warning、reset/model/disabled removal fallback，以及不产生 custom-message 历史增长或访问 fork API 的入口行为。工具输出测试还覆盖 head/tail 策略、UTF-8 边界、聚合字节/行预算、图片块保留、完整输出落盘、错误结果元数据和持久化失败 fail-open。

官方 Pi 0.84.3 的 dynamic-loading smoke 应在不调用真实 provider 的前提下运行；只验证 getActiveTools() / setActiveTools() 的 load point 和 addedToolNames 相关行为。不要在本项目测试中提交 API key、调用付费 provider 或改写官方 Pi 核心。

维护边界

官方 Pi 负责核心 runtime、prompt cache、session affinity 和 provider-specific tool serialization。pi-cache-stack 只维护工具搜索、active-tool policy、配置和诊断；通用 runtime 缺陷应提交官方 Pi/provider，而不是复制或维护一套 Pi 核心。