{"_id":"@buckeyestudio/toh-tool-session-query","name":"@buckeyestudio/toh-tool-session-query","dist-tags":{"next":"0.1.1-rc.2","latest":"0.1.1-rc.2"},"versions":{"0.1.1-rc.2":{"name":"@buckeyestudio/toh-tool-session-query","description":"Workspace-authorized model-facing session history search, trace, and event read tools","version":"0.1.1-rc.2","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-harness.git","directory":"packages/session-query/tool-session-query"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./invariant":{"types":"./lib/types/invariant.d.ts","default":"./lib/invariant.js"},"./src/*":"./src/*","./package.json":"./package.json"},"license":"MIT","author":{"name":"buckeyestudio"},"peerDependencies":{"@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/toh-llm":"^0.1.1-rc.2","@buckeyestudio/toh-system-prompt":"^0.1.1-rc.2","@buckeyestudio/toh-session":"^0.1.1-rc.2","@buckeyestudio/toh-timeout":"^0.1.1-rc.2","@buckeyestudio/toh-tools":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1","@buckeyestudio/toh-session-query":"^0.1.1-rc.2"},"dependencies":{"@buckeyestudio/schemastery":"^3.18.1"},"devDependencies":{"@buckeyestudio/toh-agent":"^0.1.1-rc.2","@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/toh-llm":"^0.1.1-rc.2","@buckeyestudio/toh-session":"^0.1.1-rc.2","@buckeyestudio/toh-session-persistence":"^0.1.1-rc.2","@buckeyestudio/toh-session-persistence-jsonl":"^0.1.1-rc.2","@buckeyestudio/toh-session-query":"^0.1.1-rc.2","@buckeyestudio/toh-session-query-sqlite":"^0.1.1-rc.2","@buckeyestudio/toh-session-title":"^0.1.1-rc.2","@buckeyestudio/toh-timeout":"^0.1.1-rc.2","@buckeyestudio/toh-system-prompt":"^0.1.1-rc.2","@buckeyestudio/toh-tool-call-timeout-policy":"^0.1.1-rc.2","@buckeyestudio/toh-tools":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1"},"_id":"@buckeyestudio/toh-tool-session-query@0.1.1-rc.2","bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","_integrity":"sha512-Zqv+qWt3foJudRMrGJbdNPhtKI62hhoT5BvzF0s3qTwCpfbEbXE+O0YF2Ayb6y0QiN6v6Udx+f/wAKbojIqWAA==","_resolved":"/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-tool-session-query-0.1.1-rc.2.tgz","_from":"file:/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-tool-session-query-0.1.1-rc.2.tgz","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-Zqv+qWt3foJudRMrGJbdNPhtKI62hhoT5BvzF0s3qTwCpfbEbXE+O0YF2Ayb6y0QiN6v6Udx+f/wAKbojIqWAA==","shasum":"0490d2b6e25ea59060b97d2294ea816517ccc1d8","tarball":"https://registry.npmjs.org/@buckeyestudio/toh-tool-session-query/-/toh-tool-session-query-0.1.1-rc.2.tgz","fileCount":14,"unpackedSize":71206,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFbw4qRzOwteHvUZWuG2jPO2AIT5uE0SCN9klmybb2CgAiAhnW6odbL/7UA7hI4+XJrpFEXl/DNPGEfZPJYluz7UXQ=="}]},"_npmUser":{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"},"directories":{},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/toh-tool-session-query_0.1.1-rc.2_1787489878374_0.5102222807646071"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-23T12:57:58.041Z","0.1.1-rc.2":"2026-08-23T12:57:58.503Z","modified":"2026-08-23T12:57:58.714Z"},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"description":"Workspace-authorized model-facing session history search, trace, and event read tools","homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-harness.git","directory":"packages/session-query/tool-session-query"},"author":{"name":"buckeyestudio"},"bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"license":"MIT","readme":"# @buckeyestudio/toh-tool-session-query\n\n[English](README.md) | 中文\n\n位于 `ctx.sessionQuery` 之上、经工作区授权的模型工具。该 opt-in 包只依赖统一接口，并注册 `session_search`、`session_event_search`、`session_trace`、`session_event_trace` 和 `session_event_read`；已发布的宿主组合默认不挂载它。\n\n## 配置\n\n| 键 | 默认值 | 含义 |\n|---|---:|---|\n| `maxSearchResults` | `100` | 在内部提供方分页中收集的最大已授权非自身命中数 |\n| `searchTimeoutMs` | `30000` | 附加到两个全文搜索工具的协作式截止时间 |\n\n调用方只能来自 `ToolExecution.exec.agent`。跨会话访问要求目标和调用方会话的 `cwd` 值严格相等；没有 `cwd` 的调用方只能检查自己。搜索绝不公开提供方游标、偏移、分页大小或模型可控上限。由于一次搜索会在内部消费与世代绑定的提供方游标，两个搜索工具都与同级工具调用排他执行；三个精确跟踪/读取工具选择并行执行。每个精确执行器都将未更改的执行信号传递给授权和服务跟踪/读取，因此取消会等待协作式持久化清理，并保留信号的精确原因。工具边界上的时间戳要求显式 `Z` 或数字偏移，并转换为包含端点的 epoch 毫秒过滤器。\n\n`session_search` 始终省略调用方会话。请求的父 id 会被去重，并在 FTS 前根据调用方工作区权限检查；只有已授权 id 会到达提供方，而缺失猜测和跨工作区猜测的行为完全相同，root 标记仍独立使用 OR。当前会话中的 `session_event_search` 会在调用它的步骤之前立即停止，因此当前 assistant 输出和已记录工具调用无法匹配自身。直接目标在跟踪、事件或标题读取前完成授权。血缘输出会用不含隐藏会话 id 的标记替换未授权祖先和后代边界。\n\n每个可信 `ctx.sessionQuery` 调用都会经过一个模型边界净化器。首先检查调用方取消，并精确保留。可获取的语料库诊断信息和提供方诊断信息（包括可安全检查的嵌套原因）会尽力记录到内部日志；不可打印的失败使用固定日志占位符。诊断格式化和错误分类各自独立受保护，因此不可打印的原因无法逃逸，也无法阻止已安全分类的外层错误；不安全的分类或日志记录则回退到固定 `SESSION_QUERY_TOOL_FAILED` 代码和消息。本地参数验证和授权错误保留精确的工具自有消息。\n\n该包刻意不执行字节或字符截断，也不导入 spill 后端。需要限制内联输出的部署应挂载 `@buckeyestudio/toh-spill-policy`，它可在执行后替换已渲染文本，同时保留完整结果。\n\n## 模型体验\n\n### 系统提示词\n\n#### 模型看到的内容\n\n模型会收到一个固定的既往历史指引章节。\n\n##### 既往历史指引\n\n```markdown\nUse session_search to find relevant work from prior sessions, or session_event_search to search earlier events in one session. Search results are cursor-free and workspace-scoped. Follow a useful hit with session_trace, session_event_trace, or session_event_read when you need lineage, relationships, or exact data.\n```\n\n#### Token 影响\n\n插件挂载期间，每次请求都存在一个固定精简章节。\n\n#### KV Cache 影响\n\n插件和指引文本不变时，前缀稳定。\n\n### 工具 schema\n\n#### 模型看到的内容\n\n模型会看到生成的 [`session_search`、`session_event_search`、`session_trace`、`session_event_trace` 和 `session_event_read` schema](../../../docs/tool-catalog.zh.md#buckeyestudiotoh-tool-session-query)。搜索过滤器会增加固定 schema token，而游标、工作区路径、输出分页和模型可控结果上限仍不存在。\n\n#### Token 影响\n\n可见期间，每次请求都会发送 5 个固定只读 schema。\n\n#### KV Cache 影响\n\n工具可见性和定义不变时，前缀稳定。\n\n### 工具结果\n\n#### 模型看到的内容\n\n每次成功调用都会发出一个纯文本块。搜索结果包含标题和最佳匹配摘录；跟踪包含全部已授权关系；事件读取包含未经删节的目标 JSON。通用 spill 策略可以将过大的内联文本替换为预览、不透明定位信息和取回指引。\n\n#### Token 影响\n\n结果取决于数据，并保留在已记录工具历史中直到压缩（compaction）；`maxSearchResults` 限制搜索命中数。\n\n#### KV Cache 影响\n\n仅追加的结果文本位于可重用请求前缀之后，不会使较早的缓存条目失效。\n\n## 已知限制与暂缓事项\n\n- 搜索最多返回部署上限，匹配更多时会请模型缩小查询；不提供延续 token。\n- 工作区身份使用保守的字符串精确 `cwd` 相等性，因此符号链接等价的路径不共享权限。\n- 未挂载通用 spill 策略的自定义组合会以内联方式接收完整跟踪和事件载荷。\n","readmeFilename":"README.zh.md","_rev":"1-f94976d0b078fed4c90e8c80bb1a6571"}