@sema-agent/server 7.43.0 → 7.44.0

package/dist/env-facts.js

@@ -1,29 +1,11 @@
-/**
- * RFC A1 (sema-internal server/docs/design/ENV-SELECT-AND-REGION-SOURCE.md) — the sandbox envFacts composer (service 半场).
- * Shape ratified REV-1: `TaskSpec.envFacts?: { profile?, capabilities?[], pkgSource?, egress? }`.
- * Core injects it into model context (escape+bound core-side); this module only COMPOSES the facts
- * from deployment-trusted sources (image catalog entry + operator region config + exec-lane posture).
- *
- * Values are bounded here too (defense-in-depth, cheap): catalog data is trusted, but a hostile row must not
- * become an unbounded prompt segment. Wire-up is flag-gated OFF until core lands the whitelist field
- * (`SANDBOX_ENV_FACTS=true` — flipping early is inert: core ignores unknown spec fields).
- */
 import { isAbsolute, join, resolve, sep } from "node:path";
 import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { createHash } from "node:crypto";
 const MAX_STR = 64;
 const MAX_CAPS = 16;
-/** scratchpadDir gets its own cap: TRUNCATING a path points at a non-existent dir (worse than absence), so an
- *  over-long path DROPS the whole field instead. The threshold is aligned to core's RENDER limit (codex F4):
- *  core's buildScratchpadSection inlines the path via `inlineUntrusted` whose default cap is 160 CODE POINTS
- *  (untrusted-text LABEL_MAX) — a 161+ char path would be truncated with "…" in the prompt, i.e. the model would
- *  be handed a FAKE path. So any path core cannot render verbatim is omitted entirely (honest-facts). */
 const MAX_PATH = 160;
 const bound = (s) => (s.length > MAX_STR ? s.slice(0, MAX_STR) : s);
-/** resumeFacts.note 是整句(64 截会砍在半句上);对齐 MAX_PATH 的 160 render 上限。 */
 const bound2 = (s) => (s.length > MAX_PATH ? s.slice(0, MAX_PATH) : s);
-/** Compose envFacts from what the deployment knows at spec-prep. Returns undefined when nothing is known
- *  (no fact beats a vacuous one — an empty block would still spend prompt tokens). */
 export function buildEnvFacts(opts) {
     const caps = Object.entries(opts.capabilities ?? {})
         .filter(([, v]) => v === true)
@@ -41,11 +23,6 @@ export function buildEnvFacts(opts) {
     };
     return Object.keys(facts).length > 0 ? facts : undefined;
 }
-/** resumeFacts 按车道能力面的单真源(部署静态;undefined=整域不声明)。取值依据见
- *  {@link SandboxEnvFacts.resumeFacts} 的逐车道注。
- *  codex 复审 medium:k8s 必须按**有效快照能力**分叉,不能只看车道名——s3Snapshot 未配=park-only,
- *  resume 是全新 pod 且**工作区不恢复**,「文件已从快照恢复」那句会让模型信赖不存在的文件(比缺席
- *  更糟的谎)。 */
 export function resumeFactsForLane(provider, caps) {
     switch (provider) {
         case "e2b":
@@ -58,39 +35,20 @@ export function resumeFactsForLane(provider, caps) {
         case "adb":
             return { scratch: "preserved" };
         case "host":
-        case undefined: // provider unset = in-process host lane
+        case undefined:
             return { scratch: "preserved" };
         default:
-            return undefined; // local-docker:容器跨 leg 存续不保证——不知道的不说
+            return undefined;
     }
 }
-// ── [820]③ scratchpad directory(single source for the FACT and the future exemptDirs)──────────────
-/** Path-safe session segment: the session id can be CALLER-SUPPLIED (body.sessionId), so it must not be able to
- *  walk the tree ("../", separators, control bytes). Allowlist [A-Za-z0-9_-] (dots excluded so ".." cannot
- *  survive), everything else becomes "_". Empty after sanitize → "_".
- *
- *  INJECTIVITY (codex F3): allowlist sanitization alone is NOT injective — "team/a" and "team?a" both map to
- *  "team_a", so two DIFFERENT sessions (possibly different principals) would collide onto ONE scratchpad dir.
- *  The segment is therefore `<readable prefix (sanitized, ≤24)>-<sha256(FULL ORIGINAL sessionId) hex ≤16>`:
- *  the hash is over the raw pre-sanitize id, so distinct ids always produce distinct segments (the prefix stays
- *  purely for human readability). Max length 24+1+16=41 (uuidv7 = 36 raw). */
 export function scratchpadSessionSegment(sessionId) {
     const cleaned = sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 24);
     const digest = createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
     return `${cleaned.length > 0 ? cleaned : "_"}-${digest}`;
 }
-/** THE scratchpad path convention: `<localDataRoot>/scratchpad/<sessionSegment>`. Session-scoped (core's
- *  prompt says "session-specific" — every task on the session shares one dir, which is the useful semantics:
- *  intermediate artifacts survive across turns/resume legs). Exported as the single source both the envFacts
- *  composer (below) and the future createFsWriteGatePolicy `exemptDirs` wiring ([820]①, 1.290) must use. */
 export function scratchpadDirFor(localDataRoot, sessionId) {
     return join(localDataRoot, "scratchpad", scratchpadSessionSegment(sessionId));
 }
-/** Resolve + CREATE the session scratchpad dir (mkdir -p, idempotent). Returns the path, or undefined when
- *  creation fails (honest-facts posture: never advertise a directory that does not exist — same class as
- *  egress/pkgSource "don't declare what you don't know"). Lifecycle: the reaper primitives live below —
- *  {@link purgeScratchpadDir}(session delete)+ {@link sweepStaleScratchpads}(mtime 周期扫),keyed by the
- *  same scratchpadDirFor convention;接线(E21 DELETE purge + 周期 sweep)在 main.ts 侧(D 组)。 */
 export async function ensureScratchpadDir(localDataRoot, sessionId) {
     const dir = scratchpadDirFor(localDataRoot, sessionId);
     try {
@@ -101,24 +59,9 @@ export async function ensureScratchpadDir(localDataRoot, sessionId) {
         return undefined;
     }
 }
-/** G3([816] 壳侧承诺③/[820]③,[1840]§四接单):**壳供** scratchpad 路径的验收门。
- *
- *  壳(cli)vendored getScratchpadDir 算出 per-session scratchpad 路径随 `TaskRequest.scratchpadDir` 发来;
- *  接受后它**优先于** server 自算(ensureScratchpadDir),喂 main.ts 的同一单点(envFacts 事实 +
- *  fs-write gate exemptDirs + additionalDirectories 根围栏)。「没到货引擎忽略 = 无害 additive」。
- *
- *  信任边界:这是 exemptDirs **放宽**输入,验收 fail-closed(任何拒收形回落自算,不 fault 任务):
- *   - 多租户(requirePrincipal)一律拒——共享 worker 盘上租户自选豁免目录=越权面;
- *   - 仅 host-semantics lane——远程沙箱 lane 的 worker 本机路径对 hands 是谎言(honest-facts 同轴);
- *   - 绝对路径 + ≤{@link MAX_PATH}(core 渲染上限同源,超限=core 只能给模型假路径)+ canonical
- *     深度 ≥3(裸 /、/tmp、/home 一整块系统目录不能当豁免域;穿越形按 resolve 归一后判);
- *   - mkdir -p 确保存在(gate 的 canonicalize 与 core 根围栏都要真目录)。
- *  敏感路径的最后一道**不在**写门折叠里(#177 起搬家):守卫集 `SENSITIVE_WRITE_PATTERNS` 由
- *  governance 拍(boot/resolve-spec.ts → applyRuntimeGovernance)无条件铸成 DENY 基线,经 tightenTaskSpec
- *  与写门 deny-wins 折叠 —— 结论不变(deny 恒赢,本函数放出的 exemptDirs 越不过它),但施加点已换。 */
 export async function acceptShellScratchpadDir(raw, opts) {
     if (typeof raw !== "string" || raw.length === 0)
-        return undefined; // additive 常态:键缺席/异形,零告警
+        return undefined;
     if (opts.requirePrincipal) {
         opts.warn("shell_scratchpad_ignored", { reason: "multi_tenant", note: "tenant-supplied exempt dir on a shared worker disk — server-computed scratchpad used instead" });
         return undefined;
@@ -136,7 +79,6 @@ export async function acceptShellScratchpadDir(raw, opts) {
         return undefined;
     }
     const canonical = resolve(raw);
-    // 深度 = 根后的非空路径段数;<3 即一整块系统级目录(/、/tmp、/home/x 之类),不能当写门豁免域。
     const depth = canonical.split(sep).filter((s) => s.length > 0).length;
     if (depth < 3) {
         opts.warn("shell_scratchpad_ignored", { reason: "too_shallow", canonical });
@@ -151,23 +93,15 @@ export async function acceptShellScratchpadDir(raw, opts) {
         return undefined;
     }
 }
-// ── 三路复审修4:scratchpad 清理原语(此前 deferred 注释=无 reap 无界增长;这里只出原语,
-// D 组把它们接到 E21 DELETE purge 与周期 sweep——签名即 seam,勿改名/改形)──────────────────────
-/** 删除一个 session 的 scratchpad 目录(rm -rf,幂等:目录不存在=no-op)。失败吞 warn 不抛——
- *  清理绝不 fault 调用它的 session-delete 路径;下一轮 {@link sweepStaleScratchpads} 仍会兜到它。 */
 export async function purgeScratchpadDir(localDataRoot, sessionId) {
     const dir = scratchpadDirFor(localDataRoot, sessionId);
     try {
-        await rm(dir, { recursive: true, force: true }); // force: ENOENT 静默=幂等
+        await rm(dir, { recursive: true, force: true });
     }
     catch (err) {
         console.warn(`scratchpad_purge_failed dir=${dir}: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-/** 周期 sweep:扫 `<localDataRoot>/scratchpad/` 下 mtime 早于 `olderThanMs` 且不属于 `activeSessionIds`
- *  (先经 {@link scratchpadSessionSegment} 映射到目录名域)的目录并删除,返回删除数。逐目录失败跳过
- *  (下一轮再兜);scratchpad 根不存在=0。mtime 取目录自身(子文件写入会碰父目录 mtime 的语义因平台而异
- *  ——诚实边界:一个只被读的活跃 session 目录可能被判过期,activeSessionIds 排除面才是活会话的真保险)。 */
 export async function sweepStaleScratchpads(localDataRoot, opts) {
     const root = join(localDataRoot, "scratchpad");
     let names;
@@ -175,7 +109,7 @@ export async function sweepStaleScratchpads(localDataRoot, opts) {
         names = await readdir(root);
     }
     catch {
-        return 0; // 根未建(还没任何 session 用过 scratchpad)= 无事可扫
+        return 0;
     }
     const activeSegments = new Set([...(opts.activeSessionIds ?? [])].map((id) => scratchpadSessionSegment(id)));
     const cutoff = Date.now() - opts.olderThanMs;
@@ -192,19 +126,17 @@ export async function sweepStaleScratchpads(localDataRoot, opts) {
             removed++;
         }
         catch {
-            /* 单目录 stat/rm 失败(并发删除/权限)→ 跳过,本轮不计数 */
         }
     }
     return removed;
 }
-/** Map the exec-lane posture to the egress fact (the model must know when downloads can't work). */
 export function egressForRemoteExec(remoteExec) {
     if (!remoteExec?.provider)
         return undefined;
     if (remoteExec.provider === "e2b")
         return remoteExec.allowInternetAccess === false ? "none" : "full";
     if (remoteExec.provider === "k8s")
-        return "full"; // kata pods egress via the cluster CNI (no allowlist face yet)
-    return undefined; // host/ssh/adb: the deployment hasn't declared a posture — say nothing rather than guess
+        return "full";
+    return undefined;
 }
 //# sourceMappingURL=env-facts.js.map