{"_id":"@buckeyestudio/toh-shell-env","name":"@buckeyestudio/toh-shell-env","dist-tags":{"next":"0.1.1-rc.2","latest":"0.1.1-rc.2"},"versions":{"0.1.1-rc.2":{"name":"@buckeyestudio/toh-shell-env","description":"Tool-independent managed TOH_* shell environment registry","version":"0.1.1-rc.2","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-harness.git","directory":"packages/shell/shell-env"},"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-shell":"^0.1.1-rc.2","@buckeyestudio/toh-session-persistence":"^0.1.1-rc.2","@buckeyestudio/toh-home-paths":"^0.1.1-rc.2","@buckeyestudio/toh-tools":"^0.1.1-rc.2","@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1"},"dependencies":{"@buckeyestudio/schemastery":"^3.18.1"},"devDependencies":{"@buckeyestudio/toh-shell":"^0.1.1-rc.2","@buckeyestudio/toh-llm":"^0.1.1-rc.2","@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/toh-home-paths":"^0.1.1-rc.2","@buckeyestudio/toh-agent":"^0.1.1-rc.2","@buckeyestudio/toh-session-persistence":"^0.1.1-rc.2","@buckeyestudio/toh-tools":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1"},"_id":"@buckeyestudio/toh-shell-env@0.1.1-rc.2","bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","_integrity":"sha512-/JOXWfmF4TD+XqjNOcOnUfGowS4WCRYEabJ/7S+1RvdOLSYeycGBoOAs347HQAvlRmNf9X635rtZqSIWPuYyAA==","_resolved":"/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-shell-env-0.1.1-rc.2.tgz","_from":"file:/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-shell-env-0.1.1-rc.2.tgz","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-/JOXWfmF4TD+XqjNOcOnUfGowS4WCRYEabJ/7S+1RvdOLSYeycGBoOAs347HQAvlRmNf9X635rtZqSIWPuYyAA==","shasum":"fe131b55c17b3116a22b80003e5266dc839917d8","tarball":"https://registry.npmjs.org/@buckeyestudio/toh-shell-env/-/toh-shell-env-0.1.1-rc.2.tgz","fileCount":9,"unpackedSize":22902,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDoJHkiugdY9eS2kFKI43/+TfVyI706GBKrZVrP1u0lXQIgf9qiJLT6WABn3+Wyfezux+8mw5L3J+pJAgGiEHzIISo="}]},"_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-shell-env_0.1.1-rc.2_1787489318025_0.13245131163895407"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-23T12:48:37.788Z","0.1.1-rc.2":"2026-08-23T12:48:38.159Z","modified":"2026-08-23T12:48:38.391Z"},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"description":"Tool-independent managed TOH_* shell environment registry","homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-harness.git","directory":"packages/shell/shell-env"},"author":{"name":"buckeyestudio"},"bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"license":"MIT","readme":"# @buckeyestudio/toh-shell-env\n\n[English](README.md) | 中文\n\n工具无关的 shell 环境插件：拥有 `ctx.shellEnv` 注册表，管理受信任的、每次执行收集的 `TOH_*` 变量，供模型可见的 shell 工具（`toh-tool-bash`、`toh-tool-pwsh`）收集进每次 shell 调用的环境。内置 shell 事实（`TOH_HOME`、`TOH_SHELL=1`、`TOH_SESSION_ID`）归注册表自身所有；其他插件可以注册额外的可枚举事实，注册随插件纤维（fiber）释放，重复所有权或未声明的运行时键会响亮失败。\n\n包根导出 Cordis 插件约定（`name`、`inject`、`Config`、`apply`）以及 `ShellEnvRegistry` 服务类及其 contributor 类型；消费方在加载本插件后使用 `ctx.shellEnv`。\n\n## Config\n\n```yaml\n- id: shell-env\n  name: '@buckeyestudio/toh-shell-env'\n  config:\n    tohHome: C:\\Users\\me\\.toh   # default: $TOH_HOME, then ~/.toh\n```\n\n## Managed environment\n\n每次前台与后台模型 shell 调用都会收到一份新收集的受信任 `TOH_*` 环境。`TOH_HOME` 是由 [`@buckeyestudio/toh-home-paths`](../../util/home-paths/README.zh.md) 解析的 Harness 主目录绝对路径（`tohHome` 配置，然后环境变量 `$TOH_HOME`，然后 `~/.toh`），`TOH_SHELL=1` 标识受管理的子进程。带 agent（智能体）的调用额外收到 `TOH_SESSION_ID=agent.session.header.id`；当活动的持久化 seam 定位到 JSONL 工件时，它们还会收到 `TOH_SESSION_JSONL=<绝对目标路径>`。JSONL 路径只是位置提示：首次 flush 之前它可能不存在，也不一定包含当前缓冲中的轮次，并且它不是授权凭据。\n\n`ctx.shellEnv` 负责收集。其他插件可以注册一个受 effect 作用域约束的 contributor，带有稳定名称、已声明的键/描述以及 `resolve(execution: ToolExecution)`；重复所有权与未声明的运行时键会响亮失败，而 `list()` 只枚举声明、不执行 provider。Harness 内置键保留 `TOH_HOME`、`TOH_SHELL` 与 `TOH_SESSION_ID`；本插件的持久化翻译器通过读取与后端无关的 `sessionPersistence.locate()` seam 拥有 `TOH_SESSION_JSONL`。\n\n```ts\nimport type { Context } from '@buckeyestudio/cordis'\nimport type {} from '@buckeyestudio/toh-shell-env'\n\nexport const inject = ['shellEnv']\n\nexport function apply(ctx: Context): void {\n  ctx.shellEnv.register({\n    name: 'deployment-region',\n    variables: { TOH_DEPLOYMENT_REGION: { description: 'Current deployment region.' } },\n    resolve: execution => execution.agent === undefined ? {} : { TOH_DEPLOYMENT_REGION: 'cn-north' },\n  })\n}\n```\n\n覆盖层根据当前 `ToolExecution` 计算，并通过专用的 `ShellExecRequest.tohEnv` 通道传递。本地执行器在合并该快照前移除所有继承的 `TOH_*`，因此嵌套 harness 与并发的父子 agent 无法泄漏陈旧身份。`process.env` 永不被修改。shell 工具的描述只教授通用的 `$TOH_*` 约定，而不是点名持久化相关的变量或添加常驻的 system-prompt 段落。\n\n## Model Experience\n\n通过 shell 工具（`toh-tool-bash`、`toh-tool-pwsh`）间接产生影响；这些工具会把该注册表的受管 `TOH_*` 快照收集进每次 shell 工具调用。\n\n#### KV Cache effect\n\n不会直接导致缓存失效；任何请求前缀变更均由上述消费方负责。\n\n## Known Limitations and Deferred Work\n\n- **`list()` 只枚举 contributor 声明的变量** — 注册表自有的内置键（`TOH_HOME`、`TOH_SHELL`、`TOH_SESSION_ID`）不包含在内，因此诊断、prompt 或 UI 代码不得把 `list()` 当作完整的环境目录。\n","readmeFilename":"README.zh.md","_rev":"1-fbe7d9095e6362fb3e5ff70068e81e56"}