@x-otto/env 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,102 @@
+# @otto/env
+
+> Environment variable standardization, path constants, and resilience configuration. Zero internal dependencies — the foundational layer of the monorepo.
+
+`@otto/env` provides the canonical path constants (dot-otto root, auth path, session dirs, etc.), environment variable normalization helpers, Claude compatibility toggles, process enumeration/liveness probes, config-layer resolution, and the unified resilience config contract. Every other package in the monorepo depends on it — it is the leaf of the dependency graph.
+
+## Installation
+
+```bash
+pnpm add @otto/env
+```
+
+## Usage
+
+```ts
+import {
+  OTTO_HOME,
+  OTTO_SESSIONS_DIR,
+  AUTH_PATH,
+  normalizeEnv,
+  normalizePath,
+  findWorkspaceRoot,
+  resolveConfigLayers,
+  listOttoProcesses,
+  isProcessAlive,
+} from '@otto/env'
+
+// Canonical paths
+console.log(OTTO_HOME) // ~/.otto (overridable via OTTO_HOME env)
+console.log(AUTH_PATH) // ~/.config/otto/auth.json
+
+// Environment variable normalization
+const port = normalizeEnv(process.env['MY_PORT'], 8080)
+
+// Find monorepo root
+const root = findWorkspaceRoot(process.cwd())
+
+// Resolve config layers (priority: project/otto > repository/otto > project/claude > user/otto > user/claude)
+const layers = resolveConfigLayers({ cwd: process.cwd(), homedir: os.homedir() })
+
+// Enumerate running otto processes
+const processes = listOttoProcesses()
+console.log(processes.map(p => `${p.pid}: ${p.command} (${p.etimeMs}ms)`))
+```
+
+## API
+
+### Path Constants
+- `OTTO_ROOT` — `.otto` directory name
+- `OTTO_HOME` — user-level root (`~/.otto`, overridable via `OTTO_HOME` env)
+- `OTTO_SESSIONS_DIR` — session storage root (`OTTO_HOME/sessions`)
+- `OTTO_SESSION_LOCKS_DIR` — write lease lock directory (`OTTO_SESSIONS_DIR/locks`)
+- `OTTO_USER_CONFIG_DIR` — user config (`~/.config/otto`)
+- `OTTO_PROJECT_DIR` — project-level `.otto` (`cwd/.otto`)
+- `OTTO_PROJECT_CONFIG_RELPATH` — project config relative path (`.otto/config.json`)
+- `AUTH_PATH` — auth credentials file path
+- `OTTO_IDENTITY_PATH` — user identity file path
+- `OTTO_USER_AGENT` — `otto/<version>` user agent string
+- `SDK_VERSION`, `BUILD_ID` — version identifiers
+
+### Service & Logging
+- `SERVICE_PORT` — default HTTP/WS port (8417)
+- `SERVICE_URL` — default service URL
+- `LOG_LEVEL` — active log level (env-derived)
+- `LOG_FILE` — log file path (empty = stderr only)
+
+### Environment Variable Normalization
+- `normalizeEnv(value, default)` — parse uint env var, fallback on invalid
+- `normalizeEnvFraction(value, default)` — parse (0,1] fraction env var
+- `normalizePath(path)` — normalize to forward-slash path
+- `findWorkspaceRoot(startDir)` — walk up to find `pnpm-workspace.yaml`
+
+### Claude Compat Toggles
+- `isClaudeCompatEnabled()` — `.claude` directory compat (default on)
+- `isClaudeSettingsCompatEnabled()` — settings translation (default off)
+- `isClaudeHooksCompatEnabled()` — hooks command bridge (default off)
+
+### Config Layers
+- `resolveConfigLayers(options)` — enumerate `.otto`/`.claude` × project/user layers
+
+### Process Management (RFC-196)
+- `listOttoProcesses(pattern?)` — enumerate otto main processes via `ps`
+- `parseOttoProcessTable(stdout)` — parse `ps` output for testing
+- `isProcessAlive(pid)` — probe process via `process.kill(pid, 0)`
+- `encodeLeaseToken(token, pid, host)` / `decodeLeaseToken(raw)` — lease lock token codec
+- `currentHostname()` — local hostname
+- `isContainerEnvironment()` — detect Docker/k8s
+
+### Resilience Config (RFC-230)
+- `DEFAULT_RESILIENCE_CONFIG` — defaults for all 6 subsystems (stream, network, mcp, schedule, error-retry, oauth)
+- `resolveResilienceConfig(explicit?, fromSettings?, warn?)` — merge 4 config layers
+- `parseResilienceEnv(raw, warn?)` — parse `OTTO_RESILIENCE_CONFIG` env
+- `validateResilienceOverride(input, warn)` — validate partial override shape
+
+## Dependencies
+
+- Internal: none
+- External: none (Node.js builtins only: `node:os`, `node:fs`, `node:path`, `node:child_process`)
+
+## Related
+
+- [Architecture](./ARCHITECTURE.md)

package/dist/index.d.ts

@@ -0,0 +1,353 @@
+//#region src/build-id.d.ts
+declare const BUILD_ID = 4512;
+//#endregion
+//#region src/config-layers.d.ts
+/**
+ * config-layers.ts —— otto/claude 配置层枚举器（RFC-032 §2 单一真源）。
+ *
+ * 把 `.otto`/`.claude` × project/user 的目录与优先级集中一处（此前散在各轴硬编码）。
+ * **职责边界**：只产出层描述（kind/scope/dir），不做文件 IO、不判断 exists、不发现 artifact、
+ * 不含信任门。纯函数、确定性、无副作用。
+ *
+ * 现状（RFC-044 review S1 + RFC-081 终局复审定档）：真实职责 = 派生插件根
+ * （`@otto/coding discoverPlugins` 取 otto 层得 `<.otto>/plugins`）。**「四轴收编中央源」经复审判定不迁**
+ * （不是待办）：command/agent 两个目录扫描轴的 precedence 已完全一致
+ * （`plugin < user/claude < user/otto < project/claude < project/otto`，各有 RFC-032 测试守护漂移），
+ * 强迁会把清晰的本地 layer 数组换成 `resolveConfigLayers().reverse().filter().map()` 徒增耦合；
+ * 且 skill/mcp 非目录扫描轴（走 SkillRegistry/McpController），不适用此枚举模型。勿再当 open gap 重做。
+ * 插件目录**不经此枚举器**接入（走 discoverPlugins → App.activePlugins() 注入各轴），故此处不含 plugin 层 kind。
+ *
+ * repository 层（RFC-130）：monorepo 根目录的 `.otto/`——当 `workspaceRoot` 与 `cwd` 不同时
+ * （如 `cwd = /repo/packages/cli`, `workspaceRoot = /repo`），在 project 与 user 之间插入
+ * `repository/otto` 层。去重：若 workspaceRoot === cwd 则 repository 与 project 同目录，跳过插入。
+ */
+type ConfigLayerKind = 'otto' | 'claude';
+type ConfigLayerScope = 'project' | 'repository' | 'user';
+interface ConfigLayer {
+  kind: ConfigLayerKind;
+  scope: ConfigLayerScope;
+  /** 该层根目录（绝对路径，正斜杠归一）。 */
+  dir: string;
+}
+interface ResolveConfigLayersOptions {
+  cwd: string;
+  homedir: string;
+  /**
+   * 是否纳入 `.claude` 层。缺省取 `isClaudeCompatEnabled()`（env 总开关）。
+   * 显式传 false 可在测试/特定场景剔除所有 claude 层。
+   */
+  claudeCompat?: boolean;
+  /**
+   * monorepo 根目录（含 `pnpm-workspace.yaml` 的目录的绝对路径）。
+   * 传入且与 `cwd` 不同时，在 project/otto 之后插入 repository/otto 层。
+   * 未传入时不插入（向后兼容纯 project+user 模式）。
+   */
+  workspaceRoot?: string;
+}
+/**
+ * 枚举配置层，数组序即优先级（高→低）：
+ *   project/otto → [repository/otto] → project/claude → user/otto → user/claude
+ *
+ * `.claude` 关闭时整体剔除其两层。repository 层仅当 `workspaceRoot` 与 `cwd` 不同时插入。
+ */
+declare function resolveConfigLayers(opts: ResolveConfigLayersOptions): ConfigLayer[];
+//#endregion
+//#region src/process-liveness.d.ts
+/** 判断进程是否存活（`process.kill(pid, 0)` 不发信号，仅探测目标是否可达）。 */
+declare function isProcessAlive(pid: number): boolean;
+/** 本机 hostname（便于消费方与 `decodeLeaseToken` 结果比对，避免各处重复 import 'node:os'）。 */
+declare function currentHostname(): string;
+/**
+ * 编码租约锁 token：`<token>:<pid>:<hostname>`。
+ *
+ * `token` 由调用方生成（`randomUUID()`），本身不含冒号；`hostname` 由 `os.hostname()` 产出，
+ * 系统规范不含冒号；三段冒号分隔天然无歧义。
+ */
+declare function encodeLeaseToken(token: string, pid: number, host: string): string;
+/** 解码结果：`pid`/`host` 为 `undefined` 表示旧格式锁文件（裸 token）或字段非法，安全降级。 */
+interface DecodedLeaseToken {
+  readonly token: string;
+  readonly pid?: number;
+  readonly host?: string;
+}
+/**
+ * 解码租约锁 token。向后兼容：解析不出 `<token>:<pid>:<host>` 三段结构（旧格式裸 token，
+ * 或内容被截断/损坏）时，整体作为 `token` 返回，`pid`/`host` 置空——消费方据此退化为现有
+ * 纯 stale-timeout 判定路径，行为与升级前完全一致，不会误判、不会崩溃。
+ *
+ * pid 合法性校验（独立评审要求）：解析出的 pid 必须是有限正整数（`Number.isFinite(n) && n > 0`），
+ * 否则一律视为非法并降级为 `undefined`。原因：
+ * - `pid <= 0`：`process.kill(0, 0)` 的语义是探测调用进程自身所在进程组是否存在，
+ *   而非探测"pid 0"这个进程是否存活——若不过滤会产生完全错误的存活判定。
+ * - `pid` 非数字（`NaN`）：`process.kill(NaN, 0)` 直接抛 `TypeError`，会导致 `isProcessAlive`
+ *   崩溃而非安全返回 false。
+ * 触发场景：锁文件被意外截断、手动编辑、或极端并发下的部分写入残留，均可能产生
+ * `token:0:host`、`token:abc:host`、`token::host` 等畸形内容。
+ */
+declare function decodeLeaseToken(raw: string): DecodedLeaseToken;
+//#endregion
+//#region src/process-enumeration.d.ts
+/** 单个 otto 主进程的枚举快照。 */
+interface OttoProcessInfo {
+  readonly pid: number;
+  readonly ppid: number;
+  /** RSS（KB，`ps` 原始口径，含共享库——勿作精确容量计算，见 RFC-196 F10）。 */
+  readonly rssKb: number;
+  /** 控制终端（`??` = 无 TTY）。 */
+  readonly tty: string;
+  /** 运行时长（毫秒，由 etime 解析）。 */
+  readonly etimeMs: number;
+  /** 完整命令行。 */
+  readonly command: string;
+  /** argv 中 `--continue <sessionId>` 的会话 ID（无则 undefined）。 */
+  readonly sessionId: string | undefined;
+  /** argv 中 `--restart-generation=<n>` 的代际计数（RFC-196 M3 引入；无则 undefined）。 */
+  readonly generation: number | undefined;
+}
+/** `ps` etime 格式：`[[dd-]hh:]mm:ss` → 毫秒。解析失败返回 0。 */
+declare function parseEtimeMs(etime: string): number;
+/**
+ * 枚举全机 otto 主进程（argv 含 `bin/otto.js` 的 node 进程）。
+ *
+ * 匹配谓词刻意收窄到主进程入口脚本——不含插件 server.mjs、node-pty spawn-helper 等
+ * 周边进程（它们的生命周期由 RFC-085 process-exit 机制覆盖，RFC-196 非目标）。
+ *
+ * @param matchPattern 主进程识别子串（默认 `bin/otto.js`；测试注入用）
+ */
+declare function listOttoProcesses(matchPattern?: string): OttoProcessInfo[];
+/** `ps` 输出解析（与 listOttoProcesses 分离供单测直接喂文本）。 */
+declare function parseOttoProcessTable(stdout: string, matchPattern?: string): OttoProcessInfo[];
+/**
+ * 容器环境探测（RFC-196 F6）：容器内 PID 1 收养是常态，`ppid==1` 不可作为孤儿强信号。
+ * 检测 `/.dockerenv` 存在或 `/proc/1/cgroup` 含 docker/kubepods。darwin 恒 false。
+ */
+declare function isContainerEnvironment(): boolean;
+//#endregion
+//#region src/resilience.d.ts
+/**
+ * 统一重试/超时/退避配置契约（RFC-230）。
+ *
+ * 归口在零依赖叶包 `@otto/env`（不新建独立包，量级参照 RFC-157 已判定的 `@otto/invariant`
+ * 29 行不该独立成包先例）。四层配置源优先级（右覆盖左）：
+ *
+ *   硬编码默认值 → env（`OTTO_RESILIENCE_CONFIG`，JSON 字符串）→ settings（`.otto/config.json`
+ *   的 `resilience` 字段）→ 程序化注入（`AppOptions.resilience`）
+ *
+ * 本文件只负责契约类型 + 默认值 + 纯函数解析/合并逻辑，不认识 `App`/`SettingsManager` 等
+ * 任何上层概念——消费方（`@otto/setting`/`@otto/coding` 等）各自在正确时机调用
+ * `resolveResilienceConfig()`，不由本文件决定何时求值（见 RFC-230 §3 D5 的"延迟冻结"设计，
+ * 那是消费方 `App` 的职责，不是本包的职责）。
+ *
+ * 不引入 zod（`@otto/env` 当前零外部依赖，见 package.json），字段级容错走手写递归校验。
+ */
+/** 统一重试/超时/退避配置的完整形状（六个子系统，全部字段均为必填——`DEFAULT_RESILIENCE_CONFIG` 保证完整性）。 */
+interface ResilienceConfig {
+  /** Agent 流式请求重试（429/5xx 等服务端响应类，指数退避）。 */
+  stream: {
+    /** 最大重试次数。默认 5。 */maxRetries: number; /** 首次重试延迟（ms）。默认 500。 */
+    initialDelayMs: number; /** 指数退避倍率。默认 2。 */
+    backoffFactor: number; /** 单次延迟上限（ms），防止 Retry-After 头失控。默认 60_000。 */
+    maxDelayMs: number;
+  };
+  /** Agent 网络断连重试（ECONNRESET/socket hang up 等，固定间隔，不做指数退避）。 */
+  networkDisconnect: {
+    /** 最大重试次数。默认 5。 */maxRetries: number; /** 固定重试间隔（ms）。默认 30_000。 */
+    intervalMs: number;
+  };
+  /** MCP 客户端重连（全局默认，per-server `mcpServerSettingSchema` 可覆盖 maxReconnectAttempts/requestTimeoutMs 两项，reconnectDelayMs 只有全局配置）。 */
+  mcp: {
+    /** 最大重连尝试次数。默认 3。 */maxReconnectAttempts: number; /** 重连退避基准延迟（ms，指数退避）。默认 500。 */
+    reconnectDelayMs: number; /** 单次请求超时（ms）。默认 30_000。 */
+    requestTimeoutMs: number;
+  };
+  /** Scheduler 定时任务失败重试（per-task maxRetries 已可配置，本字段只补充退避延迟）。 */
+  schedule: {
+    /** 每次重试之间的固定延迟（ms）。默认 0（保持现状：不改变既有 per-task 重试节奏，除非显式配置非零值）。 */retryBackoffMs: number;
+  };
+  /** TUI 对话级错误重试卡片（回合终止性错误的自动重投，RFC-147）。 */
+  errorRetry: {
+    /** 每个 prompt 的最大自动重试次数。默认 5。 */maxAttempts: number; /** 自动重试倒计时间隔（ms）。默认 30_000。 */
+    intervalMs: number;
+  };
+  /** OAuth 跨进程刷新锁（陈旧锁清理阈值 = 等待超时 = 心跳间隔×3，三者必须同步派生，见 RFC-137 规则9）。 */
+  oauth: {
+    /** 刷新锁超时（ms）。默认 15_000，下限 1_000（心跳间隔 = timeoutMs/3，过小值会导致 setInterval 忙循环，见 RFC-230 二轮评审 P1）。 */refreshLockTimeoutMs: number;
+  };
+}
+declare const DEFAULT_RESILIENCE_CONFIG: ResilienceConfig;
+/**
+ * `ResilienceConfig` 的深度可选覆盖形状。
+ *
+ * 手写局部类型，不引入 `@otto/shared` 的 `DeepPartial`——`@otto/env` 是比 `@otto/shared`
+ * 更底层的依赖叶子（`shared` 依赖 `env`，反向引入会成环），见 RFC-230 §3 D2 依赖方向核实。
+ */
+interface ResilienceConfigOverride {
+  stream?: Partial<ResilienceConfig['stream']>;
+  networkDisconnect?: Partial<ResilienceConfig['networkDisconnect']>;
+  mcp?: Partial<ResilienceConfig['mcp']>;
+  schedule?: Partial<ResilienceConfig['schedule']>;
+  errorRetry?: Partial<ResilienceConfig['errorRetry']>;
+  oauth?: Partial<ResilienceConfig['oauth']>;
+}
+/**
+ * 手写递归校验：把任意 `unknown`（通常来自 `JSON.parse` 的结果）收窄为合法的
+ * `ResilienceConfigOverride` 子集，非法部分被剔除并通过 `warn` 回调上报（不抛异常）。
+ *
+ * 校验规则（见 RFC-230 §3 D3）：
+ * - 顶层不是 object，或某个顶层 key 的值不是 object → 该顶层 key 整体剔除。
+ * - 顶层 key 不在已知的 6 个 key 之内 → 该未知 key 整体剔除（防止拼写错误静默生效误导用户）。
+ * - 子字段存在但不是"合法数值"（见 `isValidFieldValue`）→ 单字段剔除，兄弟字段不受影响。
+ * - 子字段名不在已知字段名集合内 → 该未知子字段剔除。
+ */
+declare function validateResilienceOverride(input: unknown, warn: (message: string) => void): ResilienceConfigOverride | undefined;
+/** 解析 `OTTO_RESILIENCE_CONFIG` 环境变量（JSON 字符串），非法值整体回退（无法字段级容错，因为连结构都没解析出来）。 */
+declare function parseResilienceEnv(raw: string | undefined, warn?: (message: string) => void): ResilienceConfigOverride | undefined;
+/**
+ * 合并四层配置源，返回完整的 `ResilienceConfig`（永远齐全，不含 undefined 字段）。
+ *
+ * 合并顺序（右覆盖左）：默认值 → env → settings → 程序化注入。
+ * 消费方（`@otto/coding` 的 `App`）负责在正确时机（settings 已加载后）传入 `fromSettings`，
+ * 本函数是纯合并逻辑，不关心调用时机（见 RFC-230 §3 D5）。
+ *
+ * 三层输入（env/fromSettings/explicit）**全部**经 `validateResilienceOverride` 校验，不只校验
+ * env 层——`fromSettings`/`explicit` 虽然编译期类型是 `ResilienceConfigOverride`，但运行时仍可能
+ * 携带越界数值（如 settings 层理论上应已被 `@otto/setting` 的 zod schema 拦下，但那是另一个包
+ * 的独立校验实现，不能假设它与本包的规则永远同步；`explicit` 是程序化注入，TS 类型只保证是
+ * `number` 不保证范围）。统一在合并入口做一次权威校验，避免"同一条规则两处实现、日后漂移"。
+ */
+declare function resolveResilienceConfig(explicit?: ResilienceConfigOverride, fromSettings?: ResilienceConfigOverride, warn?: (message: string) => void): ResilienceConfig;
+//#endregion
+//#region src/index.d.ts
+/** 清空队列并逐条调 sink。调用方应包一层 `(msg) => process.stderr.write(msg)` 绑定 this。 */
+declare function flushEnvWarnings(sink: (msg: string) => void): void;
+/** 取出并清空队列（测试用，不经过 sink）。 */
+declare function drainEnvWarnings(): string[];
+declare const normalizeEnv: (value: string | undefined, defaultValue: number) => number;
+/**
+ * 解析 (0,1] 区间的比例型环境变量（如压缩硬顶占窗口比例 0.90）。
+ * normalizeEnv 走 parseInt 只收正整数，无法表达小数比例——本 helper 用 parseFloat 且约束
+ * 到 (0,1]（比例语义：0 无意义、>1 超出窗口无意义），越界或非数回退默认值（不静默接受错值）。
+ */
+declare const normalizeEnvFraction: (value: string | undefined, defaultValue: number) => number;
+declare function normalizePath(path: string): string;
+/**
+ * 从 `startDir` 向上查找最近的 `pnpm-workspace.yaml`（monorepo root 标志文件），返回其所在目录。
+ * 找不到（如在非本仓的用户项目里运行）返回 `undefined`。
+ *
+ * RFC-130：单一真源实现——原先在 `@otto/coding`（`install-plugin.ts`，供 CLI `--repo` 消费）与
+ * `@otto/plugin`（`discovery.ts`，供仓库级插件发现消费）各自维护一份逐字相同的实现（copy-paste），
+ * 无法互相 import（`@otto/plugin` 是 `@otto/coding` 的依赖，反向 import 会成环）。收敛到零依赖的
+ * `@otto/env`（两者共同的底层依赖）消除维护漂移风险（终局审核 finding，2026-07-09）。
+ *
+ * 终止条件用 `dirname(dir) === dir`（到达文件系统根）而非固定层数上限——后者在深层嵌套路径下
+ * 会误截断（旧实现的 `i < 20` 上限已移除，审核 finding：该上限是冗余约束）。
+ */
+declare function findWorkspaceRoot(startDir: string): string | undefined;
+/** SDK 版本号（`@otto/env` package.json version），会话创建时戳入 metadata。 */
+declare const SDK_VERSION: string;
+declare const OTTO_USER_AGENT: string;
+declare const OTTO_ROOT = ".otto";
+/** 用户手写主配置的文件名（env 可覆盖，便于后续迁移改名）。 */
+declare const OTTO_CONFIG_FILENAME: string;
+/** 项目级主配置相对路径（`.otto/config.json`）：SettingsManager 按 workspaceDir 解析的唯一来源。 */
+declare const OTTO_PROJECT_CONFIG_RELPATH: string;
+declare const OTTO_HOME: string;
+/** 会话存储根目录（`OTTO_HOME/sessions`）：sessions.db、blob、写租约锁的共同父目录。 */
+declare const OTTO_SESSIONS_DIR: string;
+/**
+ * 会话写租约锁目录（`OTTO_HOME/sessions/locks`，RFC-159/171）——**跨消费方单源**（RFC-199 D5）。
+ *
+ * RFC-196 P0 事故（bc37146b）：cli.ts 硬编码 `~/.otto` 而 fleet-scan 走 OTTO_HOME，
+ * OTTO_HOME 被 env 覆盖时两者锁目录分裂 → `otto ps --sweep` 误判 lease-released 误杀活进程。
+ * 教训固化：所有锁/租约目录派生必须经本常量（或 OTTO_HOME 显式派生），禁止各消费方
+ * 自行拼接 homedir()。当前消费方：cli.ts（storage.session.dir）、fleet-scan.ts（只读
+ * lease 检视）、session-pool-factory.ts（writeLease lockDir = `${dir}/locks` 随 storage 派生）。
+ */
+declare const OTTO_SESSION_LOCKS_DIR: string;
+/**
+ * Session Authority daemon 的运行态目录（`OTTO_HOME/daemon`，RFC-335 M2）。
+ *
+ * 必须经 OTTO_HOME 派生、禁止消费方自行拼 `homedir()`——与 OTTO_SESSION_LOCKS_DIR 同一条
+ * 教训（RFC-196 P0 事故 bc37146b：硬编码 `~/.otto` 与 OTTO_HOME 分裂后 `otto ps --sweep`
+ * 误判并误杀活进程）。daemon state 同样承载"据此决定杀哪个进程"的语义，路径分裂的后果
+ * 是同一类误杀，故沿用单源约束。
+ */
+declare const OTTO_DAEMON_DIR: string;
+declare const OTTO_USER_CONFIG_DIR: string;
+declare const OTTO_PROJECT_DIR: string;
+/** Claude Code 项目级目录名。 */
+declare const CLAUDE_ROOT = ".claude";
+/** Claude Code 用户级目录（`~/.claude`）。 */
+declare const CLAUDE_HOME: string;
+/**
+ * `.claude` 目录兼容总开关。默认开；`OTTO_CLAUDE_COMPAT=0|false|no|off` 关闭。
+ * 读 env 在调用时求值（便于测试注入）。MVP 仅覆盖 CLAUDE.md + skills，
+ * 二者格式同构、不跨 otto 既有信任边界（otto 本就读仓库内 AGENTS.md/.otto/skills），
+ * 故默认开安全；agents/commands/settings/hooks/MCP 仍 deferred。
+ */
+declare function isClaudeCompatEnabled(): boolean;
+/**
+ * `.claude/settings.json` 翻译（高风险面）总开关。**默认关**——
+ * 需 `OTTO_CLAUDE_COMPAT_SETTINGS=1|true|yes|on` 显式启用。权限翻译有损（`Bash(cmd:*)` 不可表达
+ * → 降 ask），故 opt-in。亦受总开关 `isClaudeCompatEnabled()` 约束。
+ */
+declare function isClaudeSettingsCompatEnabled(): boolean;
+/**
+ * `.claude` hooks 命令桥（最高风险=任意命令执行）总开关。**默认关**——
+ * 需 `OTTO_CLAUDE_COMPAT_HOOKS=1|true|yes|on` 显式启用。亦受总开关 + 项目信任门约束。
+ */
+declare function isClaudeHooksCompatEnabled(): boolean;
+/**
+ * 日志文件路径。默认空字符串（不写文件，仅 stderr）；
+ * 设置 OTTO_LOG_FILE 启用文件日志（如 OTTO_LOG_FILE=~/.otto/otto.log）。
+ */
+declare const LOG_FILE: string;
+declare const SERVICE_PORT: number;
+declare const SERVICE_URL: string;
+/**
+ * RFC-341 D9：npm 源有限嗅探链——优先嗅探的内网 registry 列表（逗号分隔），缺省空。
+ *
+ * 公网源码缺省空 = 零内网痕迹（D1 隔离红线）；内网构建/用户通过环境变量注入内网 jnpm
+ * registry URL 即可让升级检查/安装先查内网 jnpm、404 再回落公网 npm。
+ * 解析：逗号分隔、去空白、去空项、去尾部斜杠归一（后续拼 `<src>/<pkg>/latest`）。
+ *
+ * call-time 解析（非模块加载快照）——嗅探链消费方 `npm-registry-sniff.ts` 每次查表都读
+ * 当前 env，既 testable（测试可运行时改 env）又始终反映真实值。
+ */
+declare const resolveNpmSniffRegistries: () => readonly string[];
+declare const LOG_LEVEL: "info" | "warn" | "error" | "debug" | "trace" | "fatal";
+declare const SETTING_OFFLINE_MODE_ENABLED: boolean;
+/**
+ * 影子模式（RFC-345）：进程级布尔，**调用时求值**（对齐 `isClaudeCompatEnabled` 范式，
+ * 而非 offline 的模块级 const）。
+ *
+ * 为什么必须函数式而非 const：`OTTO_SHADOW` 由 `packages/cli/src/cli.ts` 在**运行时**
+ * 解析 `--shadow` flag 后写入 `process.env`，而 `@otto/env` 在 cli.ts 顶部就被 import——
+ * 若用模块级 const，常量在 flag 写入前就已冻结为 false。调用时求值规避此时序陷阱，
+ * 也便于测试注入。（offline 模式可用 const 是因为 `OTTO_OFFLINE` 由外部 shell 预设、
+ * node 启动前就存在——两者注入时机不同，范式不能照搬。）
+ *
+ * 语义：为真时该进程及其全部子进程/worker 在整个生命周期内不向磁盘写入任何 otto 自有
+ * 状态（凭据/会话/记忆/配置/trace/日志），既有磁盘状态照常只读继承（overlay 语义）。
+ *
+ * 传染面：`OTTO_SHADOW` 走 `OTTO_` 前缀，由 `@otto/shared` 的 `buildAllowedEnv` 白名单
+ * 自动透传给全部 spawn 子进程；worker_threads 共享 `process.env` 天然继承——无需额外接线。
+ *
+ * 判断该开关的位置受 RFC-345 §D1 白名单约束（架构门禁强制），不得在业务层散落 `if (shadow)`。
+ */
+declare function isShadowModeEnabled(): boolean;
+declare const AUTH_PATH: string;
+/** 用户身份文件路径。`/login --service` 写入 user_id + bearer token。 */
+declare const OTTO_IDENTITY_PATH: string;
+/** 远端服务用户身份。login 后持久化到 OTTO_IDENTITY_PATH。 */
+interface UserIdentity {
+  readonly userId: string;
+  readonly token: string;
+  readonly serviceUrl: string;
+  readonly loginAt: number;
+}
+/** 从 identity.json 加载 UserIdentity。文件不存在/解析失败返回 null。 */
+declare function loadUserIdentity(path?: string): Promise<UserIdentity | null>;
+//#endregion
+export { AUTH_PATH, BUILD_ID, CLAUDE_HOME, CLAUDE_ROOT, type ConfigLayer, type ConfigLayerKind, type ConfigLayerScope, DEFAULT_RESILIENCE_CONFIG, type DecodedLeaseToken, LOG_FILE, LOG_LEVEL, OTTO_CONFIG_FILENAME, OTTO_DAEMON_DIR, OTTO_HOME, OTTO_IDENTITY_PATH, OTTO_PROJECT_CONFIG_RELPATH, OTTO_PROJECT_DIR, OTTO_ROOT, OTTO_SESSIONS_DIR, OTTO_SESSION_LOCKS_DIR, OTTO_USER_AGENT, OTTO_USER_CONFIG_DIR, type OttoProcessInfo, type ResilienceConfig, type ResilienceConfigOverride, type ResolveConfigLayersOptions, SDK_VERSION, SERVICE_PORT, SERVICE_URL, SETTING_OFFLINE_MODE_ENABLED, UserIdentity, currentHostname, decodeLeaseToken, drainEnvWarnings, encodeLeaseToken, findWorkspaceRoot, flushEnvWarnings, isClaudeCompatEnabled, isClaudeHooksCompatEnabled, isClaudeSettingsCompatEnabled, isContainerEnvironment, isProcessAlive, isShadowModeEnabled, listOttoProcesses, loadUserIdentity, normalizeEnv, normalizeEnvFraction, normalizePath, parseEtimeMs, parseOttoProcessTable, parseResilienceEnv, resolveConfigLayers, resolveNpmSniffRegistries, resolveResilienceConfig, validateResilienceOverride };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,2 @@
+import{homedir as e,hostname as t}from"node:os";import{existsSync as n,readFileSync as r}from"node:fs";import{dirname as i,join as a,normalize as o,sep as s}from"node:path";import{spawnSync as c}from"node:child_process";const l=4512;function u(e){let{cwd:t,homedir:n,workspaceRoot:r}=e,i=e.claudeCompat??q(),o=[];return o.push({kind:`otto`,scope:`project`,dir:j(a(t,`.otto`))}),r&&j(r)!==j(t)&&o.push({kind:`otto`,scope:`repository`,dir:j(a(r,`.otto`))}),i&&o.push({kind:`claude`,scope:`project`,dir:j(a(t,`.claude`))}),n&&o.push({kind:`otto`,scope:`user`,dir:j(a(n,`.otto`))}),i&&n&&o.push({kind:`claude`,scope:`user`,dir:j(a(n,`.claude`))}),o}function d(e){try{return process.kill(e,0),!0}catch{return!1}}function f(){return t()}function p(e,t,n){return`${e}:${t}:${n}`}function m(e){let t=e.indexOf(`:`);if(t===-1)return{token:e};let n=e.indexOf(`:`,t+1);if(n===-1)return{token:e};let r=e.slice(0,t),i=e.slice(t+1,n),a=e.slice(n+1),o=Number(i),s=Number.isFinite(o)&&o>0?o:void 0;return s!==void 0&&a.length>0?{token:r,pid:s,host:a}:{token:r}}function h(e){let t=e.trim().match(/^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/);if(!t)return 0;let[,n,r,i,a]=t;return(Number(n??0)*86400+Number(r??0)*3600+Number(i)*60+Number(a))*1e3}function ee(e){return e.match(/--continue\s+([0-9a-f-]{36})/)?.[1]}function te(e){let t=e.match(/--restart-generation=(\d+)/);return t?Number(t[1]):void 0}function g(e=`bin/otto.js`){let t=c(`ps`,[`-axo`,`pid=,ppid=,rss=,tty=,etime=,args=`],{encoding:`utf8`,timeout:1e4,maxBuffer:16*1024*1024});return t.status!==0||!t.stdout?[]:_(t.stdout,e)}function _(e,t=`bin/otto.js`){let n=[];for(let r of e.split(`
+`)){if(!r.includes(t))continue;let e=r.match(/^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+(.*)$/);if(!e)continue;let[,i,a,o,s,c,l]=e;l.includes(`spawn-helper`)||n.push({pid:Number(i),ppid:Number(a),rssKb:Number(o),tty:s,etimeMs:h(c),command:l,sessionId:ee(l),generation:te(l)})}return n}function v(){if(process.platform===`darwin`)return!1;try{if(n(`/.dockerenv`))return!0;if(n(`/proc/1/cgroup`)){let e=r(`/proc/1/cgroup`,`utf8`);return/docker|kubepods|containerd/.test(e)}}catch{}return!1}const y={stream:{maxRetries:5,initialDelayMs:500,backoffFactor:2,maxDelayMs:6e4},networkDisconnect:{maxRetries:5,intervalMs:3e4},mcp:{maxReconnectAttempts:3,reconnectDelayMs:500,requestTimeoutMs:3e4},schedule:{retryBackoffMs:0},errorRetry:{maxAttempts:5,intervalMs:3e4},oauth:{refreshLockTimeoutMs:15e3}},b={stream:[`maxRetries`,`initialDelayMs`,`backoffFactor`,`maxDelayMs`],networkDisconnect:[`maxRetries`,`intervalMs`],mcp:[`maxReconnectAttempts`,`reconnectDelayMs`,`requestTimeoutMs`],schedule:[`retryBackoffMs`],errorRetry:[`maxAttempts`,`intervalMs`],oauth:[`refreshLockTimeoutMs`]},x=Object.keys(b),S=new Set([`mcp.maxReconnectAttempts`,`schedule.retryBackoffMs`]);function ne(e,t,n){return typeof n!=`number`||!Number.isFinite(n)||(S.has(`${e}.${t}`)?n<0:n<=0)?!1:e===`oauth`&&t===`refreshLockTimeoutMs`?n>=1e3:!0}function C(e,t){if(typeof e!=`object`||!e||Array.isArray(e)){t(`resilience config must be an object, got: ${typeof e}`);return}let n={},r=e;for(let e of Object.keys(r)){if(!x.includes(e)){t(`resilience config has unknown top-level key "${e}", ignored`);continue}let i=e,a=r[e];if(typeof a!=`object`||!a||Array.isArray(a)){t(`resilience.${i} must be an object, got: ${typeof a}, ignored`);continue}let o=a,s={};for(let e of Object.keys(o)){if(!b[i].includes(e)){t(`resilience.${i}.${e} is not a recognized field, ignored`);continue}let n=o[e];if(!ne(i,e,n)){t(`resilience.${i}.${e} has invalid value (${JSON.stringify(n)}), ignored`);continue}s[e]=n}Object.keys(s).length>0&&(n[i]=s)}return n}function w(e,t=e=>console.warn(`[resilience-config] ${e}`)){if(!e)return;let n;try{n=JSON.parse(e)}catch(e){t(`OTTO_RESILIENCE_CONFIG is not valid JSON, ignoring entirely: ${e instanceof Error?e.message:String(e)}`);return}return C(n,t)}function T(e,t){return t?{...e,...t}:e}function re(e,t,n=e=>console.warn(`[resilience-config] ${e}`)){let r=[w(process.env.OTTO_RESILIENCE_CONFIG,n),t?C(t,n):void 0,e?C(e,n):void 0],i={stream:{...y.stream},networkDisconnect:{...y.networkDisconnect},mcp:{...y.mcp},schedule:{...y.schedule},errorRetry:{...y.errorRetry},oauth:{...y.oauth}};for(let e of r)e&&(i={stream:T(i.stream,e.stream),networkDisconnect:T(i.networkDisconnect,e.networkDisconnect),mcp:T(i.mcp,e.mcp),schedule:T(i.schedule,e.schedule),errorRetry:T(i.errorRetry,e.errorRetry),oauth:T(i.oauth,e.oauth)});return i}const E=[];function D(e){let t=E.splice(0);for(let n of t)e(n)}function O(){return E.splice(0)}const k=(e,t)=>{if(e===void 0)return t;let n=parseInt(e,10);return isNaN(n)||n<=0?(E.push(`Invalid environment variable value: ${e}. Using default: ${t}`),t):n},A=(e,t)=>{if(e===void 0)return t;let n=parseFloat(e);return isNaN(n)||n<=0||n>1?(E.push(`Invalid fraction environment variable value: ${e}. Using default: ${t}`),t):n};function j(e){return o(e).replaceAll(s===`\\`?`\\`:s,`/`)}function M(e){let t=e;for(;;){if(n(a(t,`pnpm-workspace.yaml`)))return t;let e=i(t);if(e===t)return;t=e}}function N(){try{let e=j(`${j(new URL(`.`,import.meta.url).pathname)}/../package.json`);return JSON.parse(r(e,`utf-8`)).version||`unknown`}catch(e){return console.warn(`Failed to read package version:`,e),`unknown`}}const P=N(),F=`otto/${P}`,I=`.otto`,L=process.env.OTTO_CONFIG_FILENAME||`config.json`,R=`${I}/${L}`,z=j(process.env.OTTO_HOME||`${e()}/.otto`),B=`${z}/sessions`,V=`${B}/locks`,H=`${z}/daemon`,U=j(e()+`/.config/otto`),W=j(`${process.cwd()}/${I}`),G=`.claude`,K=j(`${e()}/${G}`);function q(){let e=process.env.OTTO_CLAUDE_COMPAT?.toLowerCase();return!(e===`0`||e===`false`||e===`no`||e===`off`)}function J(){if(!q())return!1;let e=process.env.OTTO_CLAUDE_COMPAT_SETTINGS?.toLowerCase();return e===`1`||e===`true`||e===`yes`||e===`on`}function Y(){if(!q())return!1;let e=process.env.OTTO_CLAUDE_COMPAT_HOOKS?.toLowerCase();return e===`1`||e===`true`||e===`yes`||e===`on`}const X=process.env.OTTO_LOG_FILE?j(process.env.OTTO_LOG_FILE):``,Z=k(process.env.OTTO_SERVICE_PORT,8417),ie=process.env.OTTO_SERVICE_URL??`http://127.0.0.1:${Z}`,ae=()=>(process.env.OTTO_NPM_SNIFF_REGISTRIES??``).split(`,`).map(e=>e.trim().replace(/\/+$/,``)).filter(e=>e.length>0),oe=process.env.OTTO_LOG_LEVEL||(process.env.NODE_ENV===`production`?`info`:`trace`),se=process.env.OTTO_OFFLINE===`1`||process.env.OTTO_OFFLINE?.toLowerCase()===`true`||process.env.OTTO_OFFLINE?.toLowerCase()===`yes`;function Q(){let e=process.env.OTTO_SHADOW?.toLowerCase();return e===`1`||e===`true`||e===`yes`||e===`on`}const ce=j(process.env.OTTO_AUTH_PATH||`${U}/auth.json`),$=j(process.env.OTTO_IDENTITY_PATH||`${z}/identity.json`);async function le(e){let t=e??$;try{let{readFile:e}=await import(`node:fs/promises`),n=await e(t,`utf-8`),r=JSON.parse(n);return typeof r.userId==`string`&&typeof r.token==`string`&&typeof r.serviceUrl==`string`&&typeof r.loginAt==`number`?r:null}catch{return null}}export{ce as AUTH_PATH,l as BUILD_ID,K as CLAUDE_HOME,G as CLAUDE_ROOT,y as DEFAULT_RESILIENCE_CONFIG,X as LOG_FILE,oe as LOG_LEVEL,L as OTTO_CONFIG_FILENAME,H as OTTO_DAEMON_DIR,z as OTTO_HOME,$ as OTTO_IDENTITY_PATH,R as OTTO_PROJECT_CONFIG_RELPATH,W as OTTO_PROJECT_DIR,I as OTTO_ROOT,B as OTTO_SESSIONS_DIR,V as OTTO_SESSION_LOCKS_DIR,F as OTTO_USER_AGENT,U as OTTO_USER_CONFIG_DIR,P as SDK_VERSION,Z as SERVICE_PORT,ie as SERVICE_URL,se as SETTING_OFFLINE_MODE_ENABLED,f as currentHostname,m as decodeLeaseToken,O as drainEnvWarnings,p as encodeLeaseToken,M as findWorkspaceRoot,D as flushEnvWarnings,q as isClaudeCompatEnabled,Y as isClaudeHooksCompatEnabled,J as isClaudeSettingsCompatEnabled,v as isContainerEnvironment,d as isProcessAlive,Q as isShadowModeEnabled,g as listOttoProcesses,le as loadUserIdentity,k as normalizeEnv,A as normalizeEnvFraction,j as normalizePath,h as parseEtimeMs,_ as parseOttoProcessTable,w as parseResilienceEnv,u as resolveConfigLayers,ae as resolveNpmSniffRegistries,re as resolveResilienceConfig,C as validateResilienceOverride};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@x-otto/env",
+  "version": "0.1.0-alpha.0",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "tag": "alpha"
+  },
+  "scripts": {
+    "build": "tsdown && rm -f dist/*.map && sed -i '' '\\|//# sourceMappingURL=|d' dist/*.js dist/browser/index.js 2>/dev/null; true",
+    "typecheck:project": "tsc -p tsconfig.json --noEmit",
+    "typecheck:file": "tsc src/index.ts --noEmit --target ES2024 --module ESNext --moduleResolution bundler --esModuleInterop --skipLibCheck",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}