@sema-agent/server 7.126.0 → 7.127.0

package/dist/plugins/store-backend.js

@@ -12,7 +12,7 @@ import { FileRunStore } from "./file-run-store.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
 import { buildStoreOpenRefusalTail } from "./store-open-refusal.js";
 import { acquireLocalBackendWithWait } from "./store-lock-wait.js";
-import { NO_SQL_MIGRATIONS, runSqlOneTimeMigrations } from "./one-time-migrations.js";
+import { NO_SQL_MIGRATIONS, assertRetiredSchemaAbsentOnPool, runSqlOneTimeMigrations } from "./one-time-migrations.js";
 import { LocalSessionStore, createLocalSessionRepo } from "./local-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
@@ -337,11 +337,20 @@ export function createStoreBackend(config, onWarn, onError) {
         if (!config.pg)
             return undefined;
         const pool = createPgPool(pgPoolOptions(config.pg, config.dbQueryTimeoutMs), onWarn);
-        return new PgBackend(pool, config);
+        return withRetiredSchemaProbe(new PgBackend(pool, config), { dialect: "pg", pool });
     }
     if (!config.tidb)
         return undefined;
-    return new TiDBBackend(createTidbPool(config), config);
+    const pool = createTidbPool(config);
+    return withRetiredSchemaProbe(new TiDBBackend(pool, config), { dialect: "tidb", pool });
+}
+function withRetiredSchemaProbe(inner, target) {
+    const guarded = Object.create(inner);
+    guarded.ensureSchema = async () => {
+        await assertRetiredSchemaAbsentOnPool(target);
+        await inner.ensureSchema();
+    };
+    return guarded;
 }
 export async function openStoreBackendWithFallback(config, logger) {
     const sqlEngine = config.dbBackend === "mysql" || config.dbBackend === "pg" ? config.dbBackend : undefined;

package/dist/plugins/store-contracts.d.ts

@@ -36,6 +36,9 @@ import type { PeerSessionTempo, TaskResult, TaskStatus } from "@sema-agent/core"
  * 收法:**一个基类,一条重抛**。新 File 店的拒启只要 `extends StoreBootRefusalError` 就自动落在正确的
  * 一侧;忘了继承是**可见**的(它是一个必须显式选择的父类),而忘了往 if 链里加一行是不可见的。
  * (core 的 `AdoptionError` 不在本仓,改不了它的继承链 ⇒ 降级臂保留它那一条 `instanceof`,共两条。)
+ *
+ * 族的含义是「**确定的拒启表态**」,不限 File 店:SQL `ensureSchema()` 里库带着已退役 schema 的拒启(`RetiredSchemaPresentError`)也属此族。三处读它,读法一致 ——
+ * 降级臂不吞(穿过 `mayFallback`)、SQL 开库的等待窗不重试它(`store-open-wait.ts`:再等也等不来另一个答案)、「库打不开」的拒句不改写它(它自己的拒句才是真话)。
  */
 export declare class StoreBootRefusalError extends Error {
 }

package/dist/plugins/store-open-wait.js

@@ -1,4 +1,5 @@
 import { STORE_LOCK_POLL_MS } from "./store-lock-wait.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
 const REAL_CLOCK = {
     now: () => performance.now(),
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
@@ -46,6 +47,8 @@ export async function openWithinWait(open, waitMs, onWait, clock = REAL_CLOCK) {
                     throw lastFailure.error;
                 throw new StoreOpenWindowExpired(waitMs);
             case "failed": {
+                if (outcome.error instanceof StoreBootRefusalError)
+                    throw outcome.error;
                 if (lastFailure === undefined)
                     onWait({ waitMs, error: outcome.error instanceof Error ? outcome.error.message : String(outcome.error) });
                 lastFailure = { error: outcome.error };

package/dist/request-key-closure.d.ts

@@ -37,13 +37,26 @@ export type ScenarioBodyKey = (typeof TASK_BODY_SCENARIO_KEYS)[number];
 export type NamedKeysOf<T> = {
     [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
 };
-/**
- * FRESH 提交面的**顶层**键闭集裁决:受理集之外的键 ⇒ 返回拒体(调用方 400 `request.body_shape`);
- * 全部受理 ⇒ `null`。
- *
- * 判据边界(与 settings 那只同源,有意窄):只判**键名**;体本身非对象 ⇒ 本门不判(留给既有的
- * 「missing 'objective' string」那道门,免得同一个体被两句话抢答)。
- */
+/** FRESH 提交面(`POST /v1/tasks` · `/v1/tasks/stream` · `/v1/runs`)的顶层键裁决。 */
 export declare function taskBodyKeyIssue(raw: unknown): KeyClosureIssue | null;
+declare const RUN_STEER_BODY_KEYS: readonly ["mode", "priority", "text"];
+declare const CONTENT_STEER_BODY_KEYS: readonly ["content"];
+declare const INTERRUPT_STEER_BODY_KEYS: readonly ["text"];
+/** `POST /v1/runs/:id/steer` 的体形(键 = 受理集,值形由路由逐键判)。 */
+export type RunSteerBody = {
+    readonly [K in (typeof RUN_STEER_BODY_KEYS)[number]]?: unknown;
+};
+/** 子代 steer / resume 与 workflow 子代 steer 的体形。 */
+export type ContentSteerBody = {
+    readonly [K in (typeof CONTENT_STEER_BODY_KEYS)[number]]?: unknown;
+};
+/** `POST /v1/runs/:id/interrupt` 带 text 形的体形。 */
+export type InterruptSteerBody = {
+    readonly [K in (typeof INTERRUPT_STEER_BODY_KEYS)[number]]?: unknown;
+};
+/** 送话口的三种体形(闭集;词外是编译错)。 */
+export type SteerBodyForm = "run" | "content" | "interrupt";
+/** 送话口的顶层键裁决(四扇门同一只;`form` 选受理集)。 */
+export declare function steerBodyKeyIssue(raw: unknown, form: SteerBodyForm): KeyClosureIssue | null;
 export {};
 //# sourceMappingURL=request-key-closure.d.ts.map

package/dist/request-key-closure.js

@@ -32,26 +32,42 @@ const TASK_BODY_DECLARED_KEYS = [
 ];
 const TASK_BODY_SCENARIO_KEYS = ["repo"];
 const ACCEPTED_BODY = new Set([...TASK_BODY_DECLARED_KEYS, ...TASK_BODY_SCENARIO_KEYS]);
-const UNSUPPORTED_BODY = new Set(["handsReadOnly", "readDenyPatterns", "readFace", "shellGate", "writeFace"]);
-export function taskBodyKeyIssue(raw) {
+const UNSUPPORTED_BODY_KEYS = ["handsReadOnly", "readDenyPatterns", "readFace", "shellGate", "userAttachments", "writeFace"];
+const UNSUPPORTED_BODY = new Set(UNSUPPORTED_BODY_KEYS);
+const UNSUPPORTED_LABEL = "unsupported (an engine seat this service does not read from the request body — set by the deployment, or not offered in this version)";
+function closedBodyKeyIssue(raw, accepted, door) {
     if (raw === null || raw === undefined || typeof raw !== "object" || Array.isArray(raw))
         return null;
     const buckets = { unknown: [], unsupported: [] };
-    scanKeyClosure(raw, "", ACCEPTED_BODY, UNSUPPORTED_BODY, buckets);
+    scanKeyClosure(raw, "", accepted, UNSUPPORTED_BODY, buckets);
     if (buckets.unknown.length === 0 && buckets.unsupported.length === 0)
         return null;
     buckets.unknown.sort();
     buckets.unsupported.sort();
     const parts = [
-        ...(buckets.unknown.length > 0 ? [keyClosureClause(buckets.unknown, "unknown (not a task-request key — check the spelling)")] : []),
-        ...(buckets.unsupported.length > 0 ? [keyClosureClause(buckets.unsupported, "unsupported (an engine seat this service derives, never reads from the body)")] : []),
+        ...(buckets.unknown.length > 0 ? [keyClosureClause(buckets.unknown, `unknown (not ${door} key — check the spelling)`)] : []),
+        ...(buckets.unsupported.length > 0 ? [keyClosureClause(buckets.unsupported, UNSUPPORTED_LABEL)] : []),
     ];
     return {
         message: `body: unrecognized top-level key(s) — refused rather than dropped, because a dropped key reads as "in effect" to the caller. ` +
             `${parts.join("; ")}. ` +
-            `Accepted: ${[...ACCEPTED_BODY].sort().join(",")}`,
+            `Accepted: ${[...accepted].sort().join(",")}`,
         unknownKeys: buckets.unknown.slice(0, MAX_KEY_ECHO),
         unsupportedKeys: buckets.unsupported.slice(0, MAX_KEY_ECHO),
     };
 }
+export function taskBodyKeyIssue(raw) {
+    return closedBodyKeyIssue(raw, ACCEPTED_BODY, "a task-request");
+}
+const RUN_STEER_BODY_KEYS = ["mode", "priority", "text"];
+const CONTENT_STEER_BODY_KEYS = ["content"];
+const INTERRUPT_STEER_BODY_KEYS = ["text"];
+const STEER_DOORS = {
+    run: { accepted: new Set(RUN_STEER_BODY_KEYS), door: "a steer-request" },
+    content: { accepted: new Set(CONTENT_STEER_BODY_KEYS), door: "a steer-request" },
+    interrupt: { accepted: new Set(INTERRUPT_STEER_BODY_KEYS), door: "an interrupt-request" },
+};
+export function steerBodyKeyIssue(raw, form) {
+    return closedBodyKeyIssue(raw, STEER_DOORS[form].accepted, STEER_DOORS[form].door);
+}
 //# sourceMappingURL=request-key-closure.js.map

package/dist/run-acceptance.d.ts

@@ -0,0 +1,51 @@
+/**
+ * **一次提交的「受理」读法** —— 标题器只在引擎**受理**这条 run 之后起(一条律,唯一属主 = 本文件)。
+ *
+ * ## 受理是哪一刻
+ * 引擎把这次提交的 objective 收进会话的那一帧:`human_input{ carrier: "objective", delivery: "applied" }`。它是第一次模型调用
+ * 之前的最后一帧;在它之前引擎能拒的一切 —— prepare 门(`config.tool_face_control` / `config.user_invoked_skill_unknown` /
+ * `config.memory_capture_unsupported` …)、第一回合前的内联图片准入(`config.image_invalid`)、部署的 UserPromptSubmit 拦截、
+ * 开跑前的预算 / 墙钟 —— 都还没让这次输入进会话。`wiring_manifest` 不是受理:它在 prepare 通过时就出了,图片准入与提示拦截
+ * 都在它之后(core `run-identity-wiring.js` 推 wiring_manifest,`run-leg.js` 才做图片准入、推 human_input、调模型)。
+ *
+ * 只回结果、不交流的腿(verify / cascade:core 在自己里面排空每条腿的流,宿主手里没有流)看不到那一帧。它们的受理证据是结果本身:
+ * 结果里跑过 turn(`stats.turns > 0`)⇒ objective 进过会话、模型答过。**token 不是证据**:被 UserPromptSubmit 拦下的 objective 不进会话,
+ * 而同一条 run 的收尾压缩可以在已有历史的会话上花 token(turns 0、tokens > 0)—— 按 token 判会把被拦下的输入送去起名。
+ * 两种证据说的是同一件事,本文件把它们收成一只闩:先到的那一个算数,只算一次。
+ *
+ * ## 受理之后 / 之前
+ *  · 受理 ⇒ 标题器起一次(会话没有标题时它才真去生成;判据在标题器里,本文件不重复)。
+ *  · 没受理就收场(零工作的拒、受理前取消 / 拦截)⇒ 标题器不起:被拒的输入不花一次模型调用,也不被送去起名。
+ *    这次提交在提交门铸下的会话行照旧留下(无标题、零消息),与此前同 —— 「提交没让引擎受理就收场」的会话去留是另一件事,不在本文件。
+ *
+ * ## 谁喂它
+ * 三条提交腿(同步 / 流式 / durable)各在两处喂同一只:持流的那一形把每一帧交给 {@link RunAcceptance.observe};终局落行之后调一次
+ * {@link RunAcceptance.settle}。腿上不再有「什么时候起标题」的判断,标题器的唯一调用点是本文件的闩。座由提交门在 `prepareSpec` 里
+ * 随 spec 一起铸(`PreparedTaskSubmission.acceptance`);不经提交门的内部车道铸一只不带标题器的座,也就不起标题。
+ */
+export interface RunAcceptanceDeps {
+    /** 标题器(缺席 = 本部署不自动起名)。 */
+    sessionTitler?: {
+        maybeTitle(sessionId: string, objective: string, model?: string): void;
+    };
+}
+export interface RunAcceptanceInput {
+    sessionId?: string;
+    objective: string;
+    /** 本 turn 真实驱动的模型 id(标题器与 turn 同链路)。 */
+    model?: string;
+}
+export interface RunAcceptance {
+    /** 持流的腿逐帧调用(判哪一帧算受理只在这里)。不抛、不等。 */
+    observe(ev: {
+        type: string;
+    }): void;
+    /** 终局落行之后:还没在流上见过受理帧、而结果里跑过 turn(只回结果的腿)⇒ 受理。只读 `stats.turns`。不抛、不等。 */
+    settle(result: {
+        readonly stats: {
+            readonly turns: number;
+        };
+    }): void;
+}
+export declare function createRunAcceptance(deps: RunAcceptanceDeps, input: RunAcceptanceInput): RunAcceptance;
+//# sourceMappingURL=run-acceptance.d.ts.map

package/dist/run-acceptance.js

@@ -0,0 +1,27 @@
+function isObjectiveApplied(ev) {
+    if (ev.type !== "human_input")
+        return false;
+    const h = ev;
+    return h.carrier === "objective" && h.delivery === "applied";
+}
+export function createRunAcceptance(deps, input) {
+    let accepted = false;
+    const accept = () => {
+        if (accepted)
+            return;
+        accepted = true;
+        if (input.sessionId)
+            deps.sessionTitler?.maybeTitle(input.sessionId, input.objective, input.model);
+    };
+    return {
+        observe(ev) {
+            if (!accepted && isObjectiveApplied(ev))
+                accept();
+        },
+        settle(result) {
+            if (result.stats.turns > 0)
+                accept();
+        },
+    };
+}
+//# sourceMappingURL=run-acceptance.js.map

package/dist/runs.d.ts

@@ -9,6 +9,7 @@ import type { QuestionCoordinator } from "./question.js";
 import { type ToolApprovalCoordinator } from "./tool-approval.js";
 import { type FleetRunPublisher } from "./fleet/fleet-bus.js";
 import { type WorkflowCompletionInbox } from "./orchestration/workflow-completion-inbox.js";
+import type { RunAcceptance } from "./run-acceptance.js";
 import type { VerifyRoundsSpec } from "./http/verify-rounds.js";
 import type { UserInputLedger } from "./user-input-ledger.js";
 /**
@@ -91,14 +92,6 @@ export declare function taskHandleStop(registry: typeof defaultTaskRegistry, han
  * 语义上这两种时序是同一件事:本请求赢下了这条 session,而这条 session 的连接是被人断掉的。
  */
 export declare function markChildrenStoppedByUserOnAbort(signal: AbortSignal, taskId: string, principal: string | null | undefined): void;
-/**
- * A session CAS conflict is swallowed by core into a failed `TaskResult` (it is not thrown from
- * `runTaskStream`), so detect it from the result. Prefer the structured `code` (core ≥1.8); fall
- * back to the conflict wording only for older results without one.
- */
-export declare function isSessionConflictResult(result: {
-    terminal: TerminalCause;
-}): boolean;
 export declare function resumeAtHttpStatus(result: {
     terminal: TerminalCause;
 }): number | undefined;
@@ -202,8 +195,6 @@ export declare function parkToolCallId(result: unknown, cs: ParkCheckpointReader
  *  不塞进 `checkpointGate`——那是 core 的类型,server 不改其形)。非 park / 无 token / tool-less /
  *  读失败 ⇒ **同一引用**原样返回(键缺席)。graft 不负责 strip——组合序恒为 graft → strip。 */
 export declare function graftParkToolCallId<T>(result: T, cs: ParkCheckpointReader | undefined): Promise<T>;
-/** Evict a stale warm-cache entry after a cross-instance write conflict (broken-affinity backstop). */
-export declare function evictIfConflict(runner: Runner, sessionId: string | undefined, result: TaskResult): void;
 /**
  * Drive a task to completion in the background, persisting its events to the durable run log (S2).
  *
@@ -328,7 +319,12 @@ trustedInternals?: Pick<RunInternals, "workflowParkedResume">,
  * 已收敛、未告知的崩溃丢失铸成 `task.user_steer_undrained` / `task.user_followup_undrained`(`cause:"crashed"`,码按受理时的车道选);腿收场时把本腿上的受理 settle 掉。
  * 缺席 ⇒ 两手都不做(与本参数存在之前逐字相同)。
  */
-userInputLedger?: UserInputLedger): Promise<void>;
+userInputLedger?: UserInputLedger, 
+/**
+ * 这次提交的受理座(`src/run-acceptance.ts`):标题器只在引擎受理之后起。普通流形逐帧喂;只回结果的 verify / cascade 形(以及终局写口的
+ * 重试腿)终局落行之后收尾一次。缺席 ⇒ 不起标题(起标题此前由路由层在建行时做)。
+ */
+acceptance?: RunAcceptance): Promise<void>;
 /** How often a running instance refreshes its run's updated_at (liveness, independent of events).
  *  Must stay strictly below `runStaleSec` (asserted at startup AND on every hot config candidate) or the
  *  reaper would race live runs. [ref]:数值的单源是 `config-invariants.ts`(那条不变量的属主),两个消费面

package/dist/runs.js

@@ -64,13 +64,6 @@ export function markChildrenStoppedByUserOnAbort(signal, taskId, principal) {
     }
     signal.addEventListener("abort", mark, { once: true });
 }
-export function isSessionConflictResult(result) {
-    if (result.terminal.kind !== "failed")
-        return false;
-    if (result.terminal.code)
-        return result.terminal.code === "conflict";
-    return /stale write|concurrent write|conflict/i.test(result.terminal.message ?? "");
-}
 const PREPARE_REFUSAL_HTTP_STATUS = {
     "resume.session_not_found": 404,
     "rewind_snapshot.unresolvable": 422,
@@ -170,12 +163,7 @@ export async function graftParkToolCallId(result, cs) {
     const id = await parkToolCallId(result, cs);
     return id === undefined ? result : { ...result, toolCallId: id };
 }
-export function evictIfConflict(runner, sessionId, result) {
-    if (sessionId && isSessionConflictResult(result)) {
-        runner.sessions.evict?.(sessionId);
-    }
-}
-export async function runInBackground(runner, spec, runStore, taskId, metrics, principal, verify, cascade, instrumentDegenerate, planCacheProbe, persistThinking = false, inflight, preemptable, steerable, modelUsage, elicitation, elicitOwner, captureTurnAnchor, fleetPublisher, captureUserMessageAnchor, question, workflowCompletionInbox, subagentSteer, completionDiagLog, sendUserFile, promptManifests, approval, parkCheckpointReader, pendingEngineNotices, trustedInternals, userInputLedger) {
+export async function runInBackground(runner, spec, runStore, taskId, metrics, principal, verify, cascade, instrumentDegenerate, planCacheProbe, persistThinking = false, inflight, preemptable, steerable, modelUsage, elicitation, elicitOwner, captureTurnAnchor, fleetPublisher, captureUserMessageAnchor, question, workflowCompletionInbox, subagentSteer, completionDiagLog, sendUserFile, promptManifests, approval, parkCheckpointReader, pendingEngineNotices, trustedInternals, userInputLedger, acceptance) {
     const startedAt = Date.now();
     metrics?.addGauge("runs_active", 1);
     fleetPublisher?.onStart();
@@ -338,7 +326,6 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             if (verify !== undefined) {
                 const result = await runWithVerification(runner, { ...spec, taskId, signal: cancelCtrl.signal }, verify, { ...fwdInternals, ...statusSeat });
                 await flush();
-                evictIfConflict(runner, spec.sessionId, result);
                 await flushPromptManifest();
                 const safe = await withModelUsage(sealResultForExit(result));
                 await append("done", { result: safe });
@@ -346,13 +333,13 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 const plane = outwardPlane(safe.terminal);
                 await runStore.setTerminal(taskId, plane.status, safe, plane.errorMessage ?? null);
                 await releaseKeyIfZeroWorkRefusal(runStore, taskId, safe);
+                acceptance?.settle(safe);
                 recordDone(safe, plane.status);
                 return;
             }
             if (cascade !== undefined) {
                 const result = await runCascade(runner, { ...spec, taskId, signal: cancelCtrl.signal }, cascade, { ...fwdInternals, ...statusSeat });
                 await flush();
-                evictIfConflict(runner, spec.sessionId, result);
                 await flushPromptManifest();
                 const safe = await withModelUsage(sealResultForExit(result));
                 await append("done", { result: safe });
@@ -360,6 +347,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 const plane = outwardPlane(safe.terminal);
                 await runStore.setTerminal(taskId, plane.status, safe, plane.errorMessage ?? null);
                 await releaseKeyIfZeroWorkRefusal(runStore, taskId, safe);
+                acceptance?.settle(safe);
                 recordDone(safe, plane.status);
                 return;
             }
@@ -373,6 +361,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 }
                 fleetPublisher?.onEvent(ev);
                 await userInputLedger?.observeLegEvent(stream, ev);
+                acceptance?.observe(ev);
                 await flushPromptManifest();
                 switch (ev.type) {
                     case "text_delta":
@@ -406,7 +395,6 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                         await parkNeedsReview(ev.result);
                         continue;
                     }
-                    evictIfConflict(runner, spec.sessionId, ev.result);
                     {
                         const settled = causeAtDone !== undefined ? cancelledResult(causeAtDone, ev.result) : ev.result;
                         settledAsCancel = failureCodeOf(settled.terminal) === CANCELLED_CODE;
@@ -491,6 +479,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 settledAsCancel = failureCodeOf(reached.result.terminal) === CANCELLED_CODE;
                 await runStore.setTerminal(taskId, plane.status, reached.result, plane.errorMessage ?? null);
                 await releaseKeyIfZeroWorkRefusal(runStore, taskId, reached.result);
+                acceptance?.settle(reached.result);
             }
             else if (reached?.kind === "suspended") {
                 await runStore.setSuspended(taskId, reached.result);

package/dist/sandbox-egress-policy.d.ts

@@ -0,0 +1,61 @@
+/** `K8S_SANDBOX_IPV6` 闭集:`enabled` = pod 保留平台给的 IPv6(pod spec 与未引入本旋钮时逐字同形);`disabled` = pod 级 sysctl 关掉 IPv6。 */
+export declare const SANDBOX_IPV6_WORDS: readonly ["enabled", "disabled"];
+export type SandboxIpv6 = (typeof SANDBOX_IPV6_WORDS)[number];
+/** 旋钮缺席时的姿态(缺省不动 pod:关 v6 要每个节点的 kubelet 放行这两只 sysctl,没放行的集群 pod 起不来)。 */
+export declare const SANDBOX_IPV6_DEFAULT: SandboxIpv6;
+/** 一只 pod 级 sysctl(k8s `PodSecurityContext.sysctls[]` 的形)。 */
+export interface PodSysctl {
+    readonly name: string;
+    readonly value: string;
+}
+/**
+ * 沙箱 pod 的 sysctl 只有这一个属主:`disabled` ⇒ `all`(已有接口)与 `default`(之后建的接口)都关 IPv6;`enabled` ⇒ 不铸。
+ * 两只都不在 k8s 的 safe sysctl 表里 ⇒ 每个节点 kubelet 要 `--allowed-unsafe-sysctls` 点名它们,否则 pod 起不来(车道连沙箱失败,响亮)。
+ */
+export declare function sandboxPodSysctls(ipv6: SandboxIpv6): readonly PodSysctl[] | undefined;
+/** 自检读的两张表(车道侧各一只 GET)。 */
+export type EgressPolicyRead = "nodes" | "networkpolicies";
+/** 节点地址里自检判的两类(`Hostname` / `InternalDNS` / `ExternalDNS` 不是地址)。 */
+type NodeAddressType = "InternalIP" | "ExternalIP";
+export type SandboxEgressGap = {
+    readonly kind: "node_address_open";
+    readonly node: string;
+    readonly addressType: NodeAddressType;
+    readonly address: string;
+    readonly policy: string;
+    readonly ports: string;
+} | {
+    readonly kind: "policy_absent";
+} | {
+    readonly kind: "ipv6_enabled";
+} | {
+    readonly kind: "unreadable";
+    readonly what: EgressPolicyRead;
+    readonly detail: string;
+};
+/** 一只 GET 的读数:答了 2xx ⇒ 体;否则一句为什么读不到(HTTP 码 / 错误句)。 */
+export type ApiRead = {
+    readonly ok: true;
+    readonly json: unknown;
+} | {
+    readonly ok: false;
+    readonly detail: string;
+};
+export interface EgressPolicyInputs {
+    readonly nodes: ApiRead;
+    readonly policies: ApiRead;
+    /** 沙箱 pod 的标签(车道建 pod 时铸的那一份)。 */
+    readonly podLabels: Readonly<Record<string, string>>;
+    readonly ipv6: SandboxIpv6;
+}
+/**
+ * 读数 → 缺口(纯函数、全函数:不抛;顺序:读不到的表 → 策略缺席 → 逐节点逐地址 → IPv6)。一张表读不到,只跳过要它的那一判;另一张照判。
+ */
+export declare function sandboxEgressGaps(inputs: EgressPolicyInputs): SandboxEgressGap[];
+/** 读数的说法:每个缺口一行 warn `sandbox_egress_policy_gap` + 一次 `recordFailOpen`(P-DEBT);零缺口一行 info `sandbox_egress_policy_checked`。 */
+export declare function sayEgressPolicyReading(gaps: readonly SandboxEgressGap[], logger: {
+    info(msg: string, fields?: Record<string, unknown>): void;
+    warn(msg: string, fields?: Record<string, unknown>): void;
+} | undefined, namespace: string): void;
+export {};
+//# sourceMappingURL=sandbox-egress-policy.d.ts.map

package/dist/sandbox-egress-policy.js

@@ -0,0 +1,235 @@
+import { BlockList, isIP } from "node:net";
+import { recordFailOpen } from "./observability/fail-open.js";
+export const SANDBOX_IPV6_WORDS = ["enabled", "disabled"];
+export const SANDBOX_IPV6_DEFAULT = "enabled";
+export function sandboxPodSysctls(ipv6) {
+    switch (ipv6) {
+        case "enabled":
+            return undefined;
+        case "disabled":
+            return [
+                { name: "net.ipv6.conf.all.disable_ipv6", value: "1" },
+                { name: "net.ipv6.conf.default.disable_ipv6", value: "1" },
+            ];
+    }
+}
+class Unjudgeable extends Error {
+}
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function recordAt(v, where) {
+    if (!isRecord(v))
+        throw new Unjudgeable(`${where} is not an object`);
+    return v;
+}
+function optRecordAt(v, where) {
+    return v === undefined || v === null ? undefined : recordAt(v, where);
+}
+function arrayAt(v, where) {
+    if (!Array.isArray(v))
+        throw new Unjudgeable(`${where} is not a list`);
+    return v;
+}
+function optArrayAt(v, where) {
+    return v === undefined || v === null ? undefined : arrayAt(v, where);
+}
+function stringAt(v, where) {
+    if (typeof v !== "string")
+        throw new Unjudgeable(`${where} is not a string`);
+    return v;
+}
+function listItems(json, what) {
+    const items = isRecord(json) ? json.items : undefined;
+    if (!Array.isArray(items))
+        throw new Unjudgeable(`${what} answer carries no items list`);
+    return items;
+}
+const SELECTOR_OPERATORS = ["In", "NotIn", "Exists", "DoesNotExist"];
+function readSelector(v, where) {
+    const sel = optRecordAt(v, where) ?? {};
+    const labels = optRecordAt(sel.matchLabels, `${where}.matchLabels`) ?? {};
+    const matchLabels = {};
+    for (const [k, val] of Object.entries(labels))
+        matchLabels[k] = stringAt(val, `${where}.matchLabels.${k}`);
+    const matchExpressions = (optArrayAt(sel.matchExpressions, `${where}.matchExpressions`) ?? []).map((e, i) => {
+        const x = recordAt(e, `${where}.matchExpressions[${i}]`);
+        const operator = stringAt(x.operator, `${where}.matchExpressions[${i}].operator`);
+        if (!SELECTOR_OPERATORS.includes(operator))
+            throw new Unjudgeable(`${where} operator ${JSON.stringify(operator)} is not one of ${SELECTOR_OPERATORS.join(" / ")}`);
+        return { key: stringAt(x.key, `${where}.matchExpressions[${i}].key`), operator, values: (optArrayAt(x.values, `${where}.matchExpressions[${i}].values`) ?? []).map((y, j) => stringAt(y, `${where}.matchExpressions[${i}].values[${j}]`)) };
+    });
+    return { matchLabels, matchExpressions };
+}
+function selects(sel, labels) {
+    for (const [k, v] of Object.entries(sel.matchLabels))
+        if (labels[k] !== v)
+            return false;
+    for (const e of sel.matchExpressions) {
+        const has = Object.prototype.hasOwnProperty.call(labels, e.key);
+        switch (e.operator) {
+            case "In":
+                if (!has || !e.values.includes(labels[e.key]))
+                    return false;
+                break;
+            case "NotIn":
+                if (has && e.values.includes(labels[e.key]))
+                    return false;
+                break;
+            case "Exists":
+                if (!has)
+                    return false;
+                break;
+            case "DoesNotExist":
+                if (has)
+                    return false;
+                break;
+            default:
+                throw new Unjudgeable(`podSelector operator ${JSON.stringify(e.operator)} is not one of ${SELECTOR_OPERATORS.join(" / ")}`);
+        }
+    }
+    return true;
+}
+function readCidr(v, where) {
+    const cidr = stringAt(v, where);
+    parseCidr(cidr);
+    return cidr;
+}
+function readRule(v, where) {
+    const r = recordAt(v, where);
+    const to = optArrayAt(r.to, `${where}.to`);
+    const blocks = [];
+    for (const [i, peer] of (to ?? []).entries()) {
+        const ip = optRecordAt(recordAt(peer, `${where}.to[${i}]`).ipBlock, `${where}.to[${i}].ipBlock`);
+        if (ip === undefined)
+            continue;
+        blocks.push({ cidr: readCidr(ip.cidr, `${where}.to[${i}].ipBlock.cidr`), except: (optArrayAt(ip.except, `${where}.to[${i}].ipBlock.except`) ?? []).map((x, j) => readCidr(x, `${where}.to[${i}].ipBlock.except[${j}]`)) });
+    }
+    const ports = optArrayAt(r.ports, `${where}.ports`);
+    const portText = ports === undefined || ports.length === 0
+        ? "all"
+        : ports
+            .map((p, i) => {
+            const x = recordAt(p, `${where}.ports[${i}]`);
+            return `${typeof x.protocol === "string" ? x.protocol : "TCP"}/${typeof x.port === "number" || typeof x.port === "string" ? x.port : "*"}${typeof x.endPort === "number" ? `-${x.endPort}` : ""}`;
+        })
+            .join(",");
+    return { to: to === undefined || to.length === 0 ? undefined : blocks, ports: portText };
+}
+function isolatesEgress(spec, where) {
+    const types = optArrayAt(spec.policyTypes, `${where}.policyTypes`);
+    return types !== undefined ? types.map((t, i) => stringAt(t, `${where}.policyTypes[${i}]`)).includes("Egress") : spec.egress !== undefined && spec.egress !== null;
+}
+function egressPolicies(json, podLabels) {
+    const out = [];
+    for (const [i, item] of listItems(json, "networkpolicies").entries()) {
+        const p = recordAt(item, `networkpolicies[${i}]`);
+        const name = stringAt(recordAt(p.metadata, `networkpolicies[${i}].metadata`).name, `networkpolicies[${i}].metadata.name`);
+        const spec = recordAt(p.spec, `networkpolicy ${name} spec`);
+        if (!isolatesEgress(spec, `networkpolicy ${name}`) || !selects(readSelector(spec.podSelector, `networkpolicy ${name} podSelector`), podLabels))
+            continue;
+        out.push({ name, rules: (optArrayAt(spec.egress, `networkpolicy ${name} egress`) ?? []).map((r, j) => readRule(r, `networkpolicy ${name} egress[${j}]`)) });
+    }
+    return out;
+}
+function nodeAddresses(json) {
+    const out = [];
+    for (const [i, item] of listItems(json, "nodes").entries()) {
+        const n = recordAt(item, `nodes[${i}]`);
+        const node = stringAt(recordAt(n.metadata, `nodes[${i}].metadata`).name, `nodes[${i}].metadata.name`);
+        const addresses = arrayAt(recordAt(n.status, `node ${node} status`).addresses, `node ${node} status.addresses`);
+        let seen = 0;
+        for (const [j, a] of addresses.entries()) {
+            const x = recordAt(a, `node ${node} status.addresses[${j}]`);
+            const type = stringAt(x.type, `node ${node} status.addresses[${j}].type`);
+            if (type !== "InternalIP" && type !== "ExternalIP")
+                continue;
+            const address = stringAt(x.address, `node ${node} status.addresses[${j}].address`);
+            if (isIP(address) === 0)
+                throw new Unjudgeable(`node ${node} ${type} ${JSON.stringify(address)} is not an IP address`);
+            out.push({ node, addressType: type, address });
+            seen++;
+        }
+        if (seen === 0)
+            throw new Unjudgeable(`node ${node} reports no InternalIP / ExternalIP`);
+    }
+    return out;
+}
+function parseCidr(cidr) {
+    const slash = cidr.indexOf("/");
+    const net = slash < 0 ? cidr : cidr.slice(0, slash);
+    const fam = isIP(net);
+    const max = fam === 6 ? 128 : 32;
+    const prefix = slash < 0 ? max : Number(cidr.slice(slash + 1));
+    if (fam === 0 || !/^\d+$/.test(slash < 0 ? String(max) : cidr.slice(slash + 1)) || prefix > max)
+        throw new Unjudgeable(`ipBlock cidr ${JSON.stringify(cidr)} does not parse`);
+    return { net, prefix, family: fam === 6 ? "ipv6" : "ipv4" };
+}
+function inCidr(address, cidr) {
+    const c = parseCidr(cidr);
+    if ((isIP(address) === 6 ? "ipv6" : "ipv4") !== c.family)
+        return false;
+    const list = new BlockList();
+    list.addSubnet(c.net, c.prefix, c.family);
+    return list.check(address, c.family);
+}
+function ruleAllows(rule, address) {
+    if (rule.to === undefined)
+        return true;
+    return rule.to.some((b) => inCidr(address, b.cidr) && !b.except.some((x) => inCidr(address, x)));
+}
+function readTable(read, what, parse, gaps) {
+    if (!read.ok) {
+        gaps.push({ kind: "unreadable", what, detail: read.detail });
+        return undefined;
+    }
+    try {
+        return parse(read.json);
+    }
+    catch (e) {
+        gaps.push({ kind: "unreadable", what, detail: e instanceof Unjudgeable ? e.message : `answer not understood: ${e instanceof Error ? e.message : String(e)}` });
+        return undefined;
+    }
+}
+export function sandboxEgressGaps(inputs) {
+    const gaps = [];
+    const policies = readTable(inputs.policies, "networkpolicies", (json) => egressPolicies(json, inputs.podLabels), gaps);
+    const addresses = readTable(inputs.nodes, "nodes", nodeAddresses, gaps);
+    if (policies !== undefined && policies.length === 0)
+        gaps.push({ kind: "policy_absent" });
+    if (policies !== undefined && policies.length > 0 && addresses !== undefined) {
+        for (const a of addresses) {
+            for (const p of policies) {
+                const rule = p.rules.find((r) => ruleAllows(r, a.address));
+                if (rule !== undefined) {
+                    gaps.push({ kind: "node_address_open", node: a.node, addressType: a.addressType, address: a.address, policy: p.name, ports: rule.ports });
+                    break;
+                }
+            }
+        }
+    }
+    if (inputs.ipv6 === "enabled")
+        gaps.push({ kind: "ipv6_enabled" });
+    return gaps;
+}
+function effectOf(gap) {
+    switch (gap.kind) {
+        case "node_address_open":
+            return "sandbox pods can reach this node address through the egress policy — add it to sandbox.networkPolicy.nodeCidrs (kube-up lists every node's addresses) or narrow the allowing rule";
+        case "policy_absent":
+            return "no NetworkPolicy selects the sandbox pods for egress — the policy layer does not restrict sandbox egress (chart sandbox.networkPolicy.enabled, or the CNI's own policy)";
+        case "ipv6_enabled":
+            return "sandbox pods keep IPv6 — an enforcement layer that filters only IPv4 leaves the pods' IPv6 (link-local included) unfiltered; K8S_SANDBOX_IPV6=disabled turns it off in the pod (needs the two sysctls allowed by every node's kubelet)";
+        case "unreadable":
+            return `the ${gap.what} could not be read — this part of the egress check did not run (the server's k8s account needs ${gap.what === "nodes" ? "get/list on nodes (cluster scope)" : "get/list on networkpolicies in the sandbox namespace"})`;
+    }
+}
+export function sayEgressPolicyReading(gaps, logger, namespace) {
+    if (gaps.length === 0) {
+        logger?.info("sandbox_egress_policy_checked", { namespace, gaps: 0 });
+        return;
+    }
+    for (const gap of gaps) {
+        recordFailOpen("server.sandbox-egress.policy-gap", `kind=${gap.kind}${gap.kind === "unreadable" ? ` what=${gap.what}` : ""}`);
+        logger?.warn("sandbox_egress_policy_gap", { namespace, ...gap, effect: effectOf(gap) });
+    }
+}
+//# sourceMappingURL=sandbox-egress-policy.js.map