@sema-agent/server 7.3.0 → 7.5.0

package/dist/boot/lexical-path-env.js

@@ -1,116 +0,0 @@
-/**
- * #156 —— 非 host lane(e2b/k8s/ssh/adb/local-docker)写门的**纯路径规则**过渡形所用的裁决 env。
- *
- * ## 它解决的缺口
- *
- * core 的 `createFsWriteGatePolicy` / `createSensitivePathPolicy` 都把写目标交给
- * `canonicalizeTarget(env, …)` 去「问 fs 要真身」。host lane 上那个 env 就是 hand 工具真正写的那块盘,
- * 答案可信。沙箱 lane 不是:per-task 的沙箱 env 由 core 的 `executionEnvFactory` 在 spec **之后**才铸,
- * spec 期手边只有 worker 本机的 fs——拿它去裁沙箱里的路径会答错(exists/symlink 全是别人机器上的事实),
- * 而**错误的 allow 比没有门更糟**。所以 [816]/[820] 当年在沙箱 lane 诚实不挂门(wiring=undefined ⇒
- * 三个模式臂全回落 base 规则,写门整条缺席)。#153 的 ③ 号注把这笔记成了余款,#156 是它的过渡还款。
- *
- * ## 这个 env 是什么
- *
- * 一个**没有文件系统**的 env:除 `absolutePath` 外的每一个 fs 面(exists / canonicalPath / fileInfo /
- * read* / write* / listDir / createDir / …)与 shell 面都继承 core 的 `StubExecutionEnv`,
- * 恒返回 `not_supported` 错误(`readLink` 是可选面,Stub 干脆没有——core 把缺席当「symlink 不可解」,
- * 且该分支在本 env 恒不可达:exists 先错就进了 canonicalizeNewPath)——这不是伪装,这就是本 env 的诚实回答:**spec 期我们确实不知道沙箱里
- * 那块盘上有什么**。`absolutePath` 是唯一被赋予真实语义的一面,而它本来就是纯路径运算(不碰盘):
- * POSIX 绝对路径做词法归一后原样奉还,其余一律「不知道」。
- *
- * ## 由此得到的裁决语义(core dist 亲读推出,`tools/fs/safety.js` canonicalizeTarget)
- *
- *  · 绝对路径(`/…`):`absolutePath` ok ⇒ core 进 exists 探测 ⇒ 我们答 `ok(false)`(「本 env 的词法文件
- *    系统里什么都不存在」)⇒ core 走 `canonicalizeNewPath`,那里逐级 exists 同样 false ⇒ 原样返回我们给的
- *    词法绝对路径。于是 canonical key = **词法归一后的路径**,`canonicalPath` / `fileInfo` / `readLink`
- *    三面在这条路上根本不可达。
- *    🔴 `exists` 为什么必须**答 false 而不是报错**(core 5.14.0 提货批实测,A/B 已取证):5.13.0 的
- *    `canonicalizeTarget` 把 `!(exists.ok && exists.value)` 一律折成「尚不存在」;5.14.0 改成 exists **报错**
- *    即 `{ok:false, unresolvedSymlink:true}`(fail-loud 硬化,CHANGELOG 未披露),而
- *    `createSensitivePathPolicy` 对 `unresolvedSymlink` 的处置是 **deny**。两者相乘 ⇒ 沙箱 lane 上
- *    **每一个**写目标(含 `/work/proj/normal.txt`)都变成 deny,写门从「有门」退化成「全关」。
- *    对真 env 那条 fail-closed 是对的;对本 env 不是——「盘上有什么」在这里不是探测失败,而是本设计的
- *    定义域之外:词法裁决的公理就是**不看盘**。所以 `exists` 答 false 是这个 env 的诚实答案,不是伪装。
- *    (代价仍是文件头「已知残余面」里那条 symlink 不可见,与 5.13 下完全相同,没有新增放行面。)
- *    ⚖️ codex 复审 2026-08-06 对本改动提了「不该把未知 fs 状态说成确定不存在」(建议保持 fail-closed)。
- *    **逐条核对后不采纳**,理由三条,都可验证:
- *      ① 它不是本批引入的洞 —— A/B 实测 5.13.0 的 `canonicalizeTarget` 是
- *         `if (!(exists.ok && exists.value)) → canonicalizeNewPath`,exists **报错**与「不存在」同罪。
- *         本改动**恢复**该语义,没有放宽任何一条既有裁决(85 条 task-settings 钉逐条为证)。
- *      ② 建议的「保持 fail-closed」在 5.14 下的真实后果是 `createSensitivePathPolicy` 对**每一个**写目标
- *         deny —— 沙箱 lane 的写门从「有门」变成「全关」,agent 在 e2b/k8s 里一个文件都写不了。那不是
- *         更安全的门,是这条 lane 停摆;而本过渡形当初立项的整个理由就是「无门」不可接受。
- *      ③ 它指出的真残余(域内软链 + 会话豁免下可得 allow)是 2026-08-05 就成文登记的已知代价,不是新面。
- *    真正的终局解在下面「终局 seam」那段:core 5.14.0 的 `HookToolContext.env` 已到货(提货单⑥),
- *    沙箱 lane 可以在**工具执行时刻**拿真沙箱 env 裁决 —— 那一件独立成批,本批不夹带。
- *  · 相对路径 / `~/…` / Windows 盘符形:`absolutePath` 返回错误 ⇒ `canon.ok=false` ⇒ 写门直接
- *    `ask`(fail-closed)。沙箱的 cwd 在 spec 期不可知,这正是我们要的偏置——**不猜沙箱工作目录**。
- *  · 反斜杠 UNC 形(`\\host\share\…`)是唯一**不经过**本 env 的形:core 的 `canonicalizeTarget` 在入口
- *    就把它短路成 `ok:true, key=原样`(复审 2026-08-05 dist 亲读+实测)。结果不变——写门无放行域可越,
- *    落 defaultWrite 的 `ask`;sensitive 段匹配按 `[\\/]` 双分隔符切段,`\\host\share\.env` 照样 deny。
- *  · sensitivePatterns 的 deny 腿照常施加:它按 canonical key 的**路径段**做 glob 匹配,词法 key 足够,
- *    且在 `combinePolicies` 折叠里 deny 恒胜(session 豁免 / accept 域越不过)。
- *  · `isExempt`(会话「本会话不再询问」探针)是 name-keyed 的,不做 fs 裁决,任何 lane 都安全,照接。
- *
- * ## 已知残余面(过渡形的边界,不是疏漏)
- *
- *  · **symlink 形**:词法裁决看不见符号链接。沙箱里一个名字普通的软链可以指向守卫段(`.ssh` 等),
- *    我们只会给 `ask` 而不是 `deny`;host lane 上 core 会 canonicalize 出真身并 deny。相应地,core 的
- *    `unresolvedSymlink ⇒ deny` 那条腿在本 env 下永不触发。注意豁免会话下的口径(codex 复审 E):
- *    name-keyed 豁免不看路径,这类词法无害的软链目标在豁免会话里是 **allow** 而非 ask——这是本残余面
- *    在「操作员已授 don't-ask-again」情形下的完整代价,host lane 同情形仍会 deny。
- *  · **exempt/accept 域**:沙箱 lane 既无可信 cwd 也无 scratchpad 对应物,故本过渡形**一个自动放行域都
- *    不铸**(见 resolve-spec 的 wiring)。代价是 acceptEdits 在沙箱 lane 退化成与 default 同形(全 ask);
- *    这是 fail-safe 方向,与 host lane「accept 域解析不出 ⇒ 该域不生效」的哨兵先例同口径。
- *  · **`cwd` 字段**:继承 `StubExecutionEnv` 的 `"/"` 占位。本 env 只活在 policy 折叠里,core 的两个
- *    policy 都不读 `env.cwd`(相对路径基准走 `rootPath` 形参,而我们不给)——它不代表沙箱的工作目录。
- *
- * ## 终局 seam
- *
- * 正解是让写门在**工具执行时刻**拿到真沙箱 env:core [2751] 排期的 `HookToolContext.env` 只读能力窄面
- * **已随 core 5.14.0 到货**(`canonicalPath`/`exists`/`readLink`/`cwd()` 四原语,逐成员在场即真有该原语;
- * 注意 `cwd()` 是 env 自己的工作目录、**不是**任务跟踪 cwd)。接它 = 本过渡形整体退役换正解,沙箱 lane
- * 与 host lane 走同一条真 fs 裁决,上面三条残余面一并消失。**本批不做**(它改的是裁决时刻与 wiring 形状,
- * 属独立设计件);在它落地之前,上面三条残余面按原样有效。
- */
-import { posix } from "node:path";
-import { FileError, StubExecutionEnv, err, ok } from "@sema-agent/core";
-/** 词法归一:纯字符串运算,折 `.` / `..` / 重复分隔符,不碰 fs。
- *  `posix.normalize` 把 `..` 在根部截断(`/../x` → `/x`),与「沙箱根之上没有东西」的语义一致。
- *  尾部分隔符统一剥掉(根 `/` 除外),让同一目标只有一个 key ——前缀判域靠的就是 key 的唯一性。
- *  (core 内部有同形的 `normalizeAbsPathLexically`,但未从包根导出;此处是 Node 标准库的等价运算,
- *   不是它的抄本——若日后 core 导出,这里应改为直接复用。) */
-function normalizeAbsolutePathLexically(path) {
-    const collapsed = posix.normalize(path.replace(/^\/+/, "/"));
-    return collapsed.length > 1 ? collapsed.replace(/\/+$/, "") : collapsed;
-}
-/**
- * 无文件系统的路径裁决 env(见文件头)。只覆写 `absolutePath` 一面,其余全部继承 `StubExecutionEnv`
- * 的 `not_supported` ——**继承而非逐一手写**是刻意的:core 日后给 `ExecutionEnv` 加必填面时,新面会
- * 随 `StubExecutionEnv` 一起到位并保持同一个诚实答案,不会在这里留下一个悄悄编出来的假答案。
- */
-export class LexicalPathExecutionEnv extends StubExecutionEnv {
-    absolutePath(path) {
-        // POSIX 绝对形是沙箱 lane(全 Linux)上 hand 工具的书面契约形。其余一切——相对路径、`~`、
-        // `C:\…`——在 spec 期都无法诚实解析成一个沙箱内的绝对路径,返回错误让 core 落 ask。
-        // (反斜杠 UNC 形根本到不了这里:core 在 canonicalizeTarget 入口短路,见文件头「由此得到的裁决语义」。)
-        // codex 复审 A(2026-08-05):含 NUL 的字符串不是合法 POSIX 路径(任何 fs 面都写不进去),但词法归一
-        // 会照样给它铸出 canonical key——`\0` 尾巴让守卫段 glob 失配,豁免会话下还能拿 allow。拒收让 canon
-        // 在豁免咨询**之前**就失败 ⇒ 恒 ask。
-        if (path.includes("\u0000")) {
-            return Promise.resolve(err(new FileError("not_supported", "this environment adjudicates paths lexically and rejects a path containing a NUL byte (not a representable POSIX path)", path)));
-        }
-        if (!path.startsWith("/")) {
-            return Promise.resolve(err(new FileError("not_supported", "this environment adjudicates paths lexically and cannot resolve a non-absolute path (the sandbox working directory is unknown at spec time)", path)));
-        }
-        return Promise.resolve(ok(normalizeAbsolutePathLexically(path)));
-    }
-    /** 词法文件系统是**空的**:没有任何路径存在。见文件头「绝对路径」那条的 🔴 段——这一面是 core 5.14.0
-     *  把 `exists` 报错改判 `unresolvedSymlink`(⇒ sensitive policy deny)之后,「不看盘」这条公理在新契约
-     *  下的**唯一**诚实表达;报错会被读成「探测失败」,而本 env 从来不探测。 */
-    exists(_path) {
-        return Promise.resolve(ok(false));
-    }
-}
-//# sourceMappingURL=lexical-path-env.js.map