@sema-agent/server 7.2.0 → 7.3.0

package/dist/config.js

@@ -188,6 +188,30 @@ const CONFIG_NOTICES = [];
 export function drainConfigNotices() {
     return CONFIG_NOTICES.splice(0, CONFIG_NOTICES.length);
 }
+/** #157([2762]§五,F 类观测,零行为变化)—— 本次 boot 的执行车道落点 + 它的来源。
+ *  为什么单开一格:REMOTE_EXEC 未设/空串时的落点由 CONFIG_PROVIDER 隐式决定(local ⇒ host 真机,其余 ⇒
+ *  进程内 stub),而这个落点此前在日志里零留痕 —— 运维拿到一台 worker,无从确认「它跑的是哪条执行通道、
+ *  是显式配的还是默认落的」。与 CONFIG_WARNINGS / CONFIG_NOTICES 同为 pre-logger 收集(config 解析早于
+ *  logger 建立),但级别是 **info**:这是每次 boot 都成立的常态事实,不是异常,而 CONFIG_NOTICES 那一格
+ *  固定按 warn 排空。
+ *  单槽(不是队列):一次 boot 只有一个落点;重复 loadConfig(测试)覆写即可,不会堆积。
+ *  ⚠️ 写入时机=装配尾(见 loadConfig),不是解析途中:写早了,任何**后置**拒启(limits 域数值、跨域
+ *  不变量)都会留下一条「其实没启起来」的落点;而 loadConfig 开头的清槽保证失败的一轮不会把**上一轮**
+ *  的落点串给下一次排空(交叉复审 medium,2026-08-06)。
+ *  ⚠️ 边界:记的是 **ENV 解析出的**落点。local 形的 `config.d/remote-exec.json` 覆写发生在 main.ts 的
+ *  applyLocalRemoteExec(晚于本行排空),它自己另记 `remote_exec_from_file` —— 两行合读才是最终 lane。 */
+let EXEC_LANE_NOTICE;
+/** 从**已装配好的** remoteExec 派生落点一行(而不是在 REMOTE_EXEC 那条三元链的各臂里分别记账):
+ *  分臂记账要靠「校验过了 ⇒ 必落对应那一臂」这条人肉维护的同源假设,链子哪天多一臂就悄悄失真;
+ *  取装配结果则天然跟随。`in-process` = REMOTE_EXEC 未设的进程内 stub 姿态,沿用既有词表
+ *  (config-center/types.ts 的 provider 词表、run-local 的 `?? "in-process"` 同名)。 */
+function buildExecLaneNotice(remoteExec) {
+    const explicit = process.env.REMOTE_EXEC !== undefined && process.env.REMOTE_EXEC !== "";
+    return {
+        lane: remoteExec?.provider ?? "in-process",
+        source: explicit ? "explicit-env" : process.env.CONFIG_PROVIDER === "local" ? "default-local-provider" : "default-unset",
+    };
+}
 /** F10 (codex audit): drain + log BOTH pre-logger diagnostic collectors (S20 soft-knob warnings + [792]④ boot
  *  notices) in one place. EVERY entrypoint that calls loadConfig() then builds a logger must call this right
  *  after (main.ts, run-local.ts) — a new entry that forgets it would silently drop operator-facing diagnostics
@@ -197,6 +221,13 @@ export function logConfigDiagnostics(logger) {
         logger.warn("config_env_invalid_using_default", { env: w.env, raw: w.raw });
     for (const n of drainConfigNotices())
         logger.warn(n.event, n.fields);
+    // #157 F 类观测:执行车道落点一行(见 EXEC_LANE_NOTICE 头注)。无条件发 —— boot 期本来就只跑一次,
+    // 不需要 once-per-hit 抑制。先取后清:排空语义与上面两格一致(重复调用不重放同一条)。`info` 与
+    // `debug` 同为可选,理由同上 —— 老 embedder 传进来的 warn-only logger 仍能编译、仍拿得到警告。
+    const laneNotice = EXEC_LANE_NOTICE;
+    EXEC_LANE_NOTICE = undefined;
+    if (laneNotice && logger.info)
+        logger.info("exec_lane_selected", { lane: laneNotice.lane, source: laneNotice.source });
     // design/158 N9 (polarity self-report): a `*_ENABLED` suffix does NOT carry its default — the repo grew four
     // dialects for it (opt-in / opt-out / posture tri-state / negative name). Rather than force operators to read
     // config.ts to learn what a knob does when unset, boolEnv-parsed knobs register themselves and we print one
@@ -874,6 +905,45 @@ export function formatUnmatchableToolNames(source, bad) {
     return (`${source} names tool(s) that can never match a live tool (core 5.0.0 RB-476 — the alias/auto-prefix folds are gone): ` +
         bad.map((b) => `${b.name} → ${b.guidance}`).join("; "));
 }
+/**
+ * #151 流内审批协议(design/172)的九键段(车3 刀 3a 五键 + 车5 收敛器四键)。
+ *
+ * **总开关默认 false** ⇒ 全链逐字现行为(不发 approval_request、不落 ask 行、不起收敛器腿、窗仍是
+ * `DEFAULT_APPROVAL_TTL_MS`)。窗/帽四键沿用 `numEnv` fail-loud 形(坏形启动期炸,不静默折 NaN);
+ * 车5 的四键一律 **`numEnvBounded`**(§9 C6:batch 整数 ≥1 有上帽,grace/TTL 非负有界)——它们直接
+ * 决定 reaper 每 tick 的库压与「多久算遗孤」,一个手滑的 `0` 或 `1e12` 都是运维事故面。
+ *
+ * 🔴 跨旋钮不变量(§9 C6,`#157` 三分类 P 族姿势):`ADHOC_GRACE < ORPHAN_TTL`。破坏形**拒启** ——
+ * 若 adhoc 宽限 ≥ 遗孤 TTL,判据 5 会先于判据 4 触发,一条 adhoc 腿拿到的归因就成了
+ * `orphan_ttl_exceeded`(「遗孤兜底」)而不是 `adhoc_leg_no_durable_domain`(「结构上无对账域」),
+ * 审计面从此读不出真实成因。默认值(60s vs 7d)自然满足;只有显式改坏才会撞上。
+ */
+function streamApprovalConfig() {
+    const cfg = {
+        enabled: boolEnv("STREAM_APPROVAL_ENABLED", false),
+        windowMs: numEnv("STREAM_ASK_WINDOW_MS", "60000"),
+        replayMax: numEnv("STREAM_APPROVAL_REPLAY_MAX", "50"),
+        admitMaxPerTask: numEnv("STREAM_APPROVAL_ADMIT_MAX_PER_TASK", "32"),
+        admitMaxPerOwner: numEnv("STREAM_APPROVAL_ADMIT_MAX_PER_OWNER", "256"),
+        reconcileBatch: numEnvBounded("STREAM_APPROVAL_RECONCILE_BATCH", "200", 1, 10_000),
+        pendingGraceMs: numEnvBounded("STREAM_APPROVAL_PENDING_GRACE_MS", "30000", 0, 3_600_000),
+        adhocGraceMs: numEnvBounded("STREAM_APPROVAL_ADHOC_GRACE_MS", "60000", 0, 86_400_000),
+        orphanTtlMs: numEnvBounded("STREAM_APPROVAL_ORPHAN_TTL_MS", String(7 * 24 * 60 * 60 * 1000), 60_000, 90 * 24 * 60 * 60 * 1000),
+    };
+    // 🔴 不变量的**正确形**(codex 交叉复审 C7,2026-08-06 验真):两条臂量的不是同一个起点 ——
+    // 判据 4 在 `expiresAtMs + ADHOC_GRACE` 触发,而 `expiresAtMs ≈ createdAtMs + WINDOW`;判据 5 在
+    // `createdAtMs + ORPHAN_TTL` 触发。只比 `ADHOC_GRACE < ORPHAN_TTL` 会漏掉窗:例如 WINDOW 与
+    // ORPHAN_TTL 等长时校验放行,但遗孤兜底必定先到,adhoc 腿的归因被写成 `orphan_ttl_exceeded`。
+    // 正确判据 = `WINDOW + ADHOC_GRACE < ORPHAN_TTL`(两边都是有界有限值,不会溢出)。
+    if (cfg.windowMs + cfg.adhocGraceMs >= cfg.orphanTtlMs) {
+        throw new Error(`env STREAM_ASK_WINDOW_MS=${cfg.windowMs} + STREAM_APPROVAL_ADHOC_GRACE_MS=${cfg.adhocGraceMs} must be STRICTLY LESS than STREAM_APPROVAL_ORPHAN_TTL_MS=${cfg.orphanTtlMs} — the adhoc arm fires at (createdAt + window + grace) while the orphan backstop fires at (createdAt + ttl); if the backstop wins, every adhoc-leg row is attributed "orphan_ttl_exceeded" instead of "adhoc_leg_no_durable_domain" (attribution honesty, design/172 §6.1)`);
+    }
+    // 整数门(batch 是行数,不是时长):`numEnvBounded` 只管区间,`200.5` 会一路走到 SQL `LIMIT` 上。
+    if (!Number.isInteger(cfg.reconcileBatch)) {
+        throw new Error(`env STREAM_APPROVAL_RECONCILE_BATCH=${cfg.reconcileBatch} must be an INTEGER row count`);
+    }
+    return cfg;
+}
 function parseApprovalDomain(ctx) {
     const { postureOn } = ctx; // 跨域入参②:posture 三态(single-user turnkey ⇒ HITL 面默认 ON)
     // design/80 D-G: the direct-connect approval door anchors (all must be present to ACTIVATE; fail-closed).
@@ -929,6 +999,13 @@ function parseApprovalDomain(ctx) {
         },
         askQuestionEnabled: postureOn("ASK_QUESTION_ENABLED"), // §4④ AskUserQuestion live HITL; posture-gated (single-user → ON)
         toolApprovalEnabled: postureOn("TOOL_APPROVAL_ENABLED"), // [816]/[820]② live tool-approval HITL; posture-gated (single-user → ON), mirrors askQuestion
+        // #151 车2(design/172 §3.3 D3):ToolApprovalCoordinator 窗长三元的安全余量。numEnv fail-loud 形,
+        // 照邻居旋钮(approvalTimeoutSec 等)抄——坏形（非数字)在启动期炸,不静默折成 NaN。
+        streamAskWindowMarginMs: numEnv("STREAM_ASK_WINDOW_MARGIN_MS", "10000"),
+        // #151 车3 刀 3a(design/172 流内审批协议):五键。**总开关默认 false** ⇒ 全链逐字现行为(不发
+        // approval_request、不落 ask 行、窗仍是 DEFAULT_APPROVAL_TTL_MS)。窗/帽四键与邻居旋钮同 numEnv
+        // fail-loud 形——坏形在启动期炸,不静默折 NaN。语义与三问分析见 config-types.ts 的 StreamApprovalConfig。
+        streamApproval: streamApprovalConfig(),
         // [875]a 成文:0(缺省)= durable HITL 无限期等人,时间型 reapSuspended 不跑;file/memory lane 的回收
         // 探针只在 DURABLE_APPROVAL=true 时注入(无 durable 的部署两只 suspended 回收器恒 NO-OP,parked 行的
         // 恢复把手 = POST /v1/runs/:id/cancel,[868]①)。checkpoint 过期驱动的那只不受本旋钮门控。
@@ -1099,6 +1176,37 @@ function parseOrchestrationDomain(ctx) {
         }
         return boolEnv("LSP_HOST_ENABLED", true);
     })();
+    // ── #157([2755] tag `server.exec-lane.silent-downgrade-to-host`,P 类车道选择)——执行车道的
+    // fail-closed 校验。旧形:REMOTE_EXEC 点名了一条 lane 但必需 env 不全(或值拼错不在闭集里)时,下面
+    // 三元链的合取逐臂失败、静默滑穿到尾部 ⇒ CONFIG_PROVIDER=local 落 host(worker 本机、无隔离)、否则落
+    // in-process stub,且两种跑法的成功回执同形(status=completed,test [2753]§2 实测「在哪儿跑的」对外
+    // 零信息量)。操作员配了沙箱却在真机上跑 = P 类判据表的样板案,必须拒启点名,不静默降级。
+    // 语义边界:REMOTE_EXEC **未设**(或空串,env 管理器的显式「不选」形)不是降级,是文档化的部署姿态
+    // (local ⇒ host 默认,fleet ⇒ stub),照旧;拒启只咬「点了名却配不齐/认不出」。缺失点名要**准**——
+    // 只列缺的件,不列 lane 的全量需求(WORKFLOW_SIZE_GUIDELINE / MEMORY_SYNC_* 半配拒启同族先例)。
+    {
+        const lane = process.env.REMOTE_EXEC;
+        if (lane !== undefined && lane !== "") {
+            const REQUIRED_ENVS_BY_LANE = {
+                e2b: ["E2B_API_KEY"],
+                k8s: ["K8S_SANDBOX_IMAGE"],
+                ssh: ["SSH_HOST", "SSH_USER", "SSH_PRIVATE_KEY"],
+                adb: ["ADB_SERIAL"],
+                host: [],
+                "local-docker": ["DOCKER_IMAGE"],
+            };
+            const required = Object.hasOwn(REQUIRED_ENVS_BY_LANE, lane) ? REQUIRED_ENVS_BY_LANE[lane] : undefined;
+            if (required === undefined) {
+                throw new Error(`REMOTE_EXEC="${lane}" is not an execution lane — valid: e2b | k8s | ssh | adb | host | local-docker. ` +
+                    `An unrecognized value used to fall through to the host/in-process lane silently; refusing to start instead (#157).`);
+            }
+            const missing = required.filter((name) => !process.env[name]);
+            if (missing.length > 0) {
+                throw new Error(`REMOTE_EXEC=${lane} but required env ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} missing/empty — ` +
+                    `refusing to start rather than silently downgrading to the host/in-process lane (#157; unset REMOTE_EXEC if you meant no sandbox lane).`);
+            }
+        }
+    }
     return {
         remoteExec: process.env.REMOTE_EXEC === "e2b" && process.env.E2B_API_KEY
             ? {
@@ -1375,8 +1483,8 @@ const MODEL_PLANE_GROUP_KEYS = [
 const APPROVAL_GROUP_KEYS = [
     "approvalRequire", "approvalDeny", "approvalTimeoutSec", "approvalAutoBudget", "approvalNeverAuto",
     "approvalHmacKeys", "durableApproval", "directApprovalDoor", "directDoorActive", "resourceSuspend",
-    "resourceSuspendTtlSec", "askQuestionEnabled", "toolApprovalEnabled", "mcpElicitation", "sensitiveWritePatterns",
-    "manualModeShellGate",
+    "resourceSuspendTtlSec", "askQuestionEnabled", "toolApprovalEnabled", "streamAskWindowMarginMs", "streamApproval", "mcpElicitation",
+    "sensitiveWritePatterns", "manualModeShellGate",
 ];
 const MEMORY_GROUP_KEYS = [
     "memoryEngineEnabled", "memoryEngineDir", "memoryEngineRemoteLaneAllowed", "memoryEngineBackend", "memoryScope",
@@ -1459,6 +1567,11 @@ export function attachConfigGroups(flat) {
     return flat;
 }
 export function loadConfig() {
+    // #157:落点清槽必须排在**第一条**语句 —— 比下面那组同类复位还早一格,因为 rejectRetiredEnvs 本身会抛,
+    // 而一轮抛出的 loadConfig 绝不能把**上一轮**成功解析的落点留在槽里被下一次排空读成本轮事实
+    // (交叉复审第二轮,2026-08-06)。下面三格同族收集器在这条最早拒启路径上仍有同形残留,那是既有面、
+    // 且都按 warn 排空,不在本件射程内。
+    EXEC_LANE_NOTICE = undefined;
     rejectRetiredEnvs(); // [2354] 退役 env 墓碑:在场即拒启带新名指引
     CONFIG_WARNINGS.length = 0; // repeated loadConfig() calls (test setup) must not accumulate stale warnings
     CONFIG_NOTICES.length = 0;
@@ -1528,6 +1641,18 @@ export function loadConfig() {
             throw new Error(`DIRECT_APPROVAL_DOOR=true but D-G anchors are missing: ${missing.join(", ")} — refusing to start a half-open direct door (design/80 D-G boot invariant)`);
         }
     }
+    // 🔴 boot invariant (#157-①, silent-downgrade-batch-20260805 普查候选 1/2): the BFF multi-tenant durable form
+    // (DURABLE_APPROVAL=true + REQUIRE_PRINCIPAL=true, direct door OFF) had NO invariant — the D-G one above only
+    // binds when DIRECT_APPROVAL_DOOR=true. On that form the four READ surfaces in approvals-assistant.ts
+    // (GET /v1/approvals, /stream, /v1/assistant/inbox, /tasks) scope by the bare isOperator, whose empty-list
+    // "true-for-all" lets ANY authenticated tenant principal list/subscribe every other tenant's pending queue
+    // (redacted tool-input previews + decide-binding fields) and inspect arbitrary owners via ?owner. The WRITE
+    // surfaces (decide/preempt/resume/plan_review) already use explicitOperatorOk and were never exposed. The
+    // single-tenant legacy semantic (REQUIRE_PRINCIPAL unset — the shared service token IS the operator boundary)
+    // is deliberately preserved: only the multi-tenant form is a hole. Refuse to start it.
+    if (dgDurable && requirePrincipal && dgOperators.length === 0) {
+        throw new Error("DURABLE_APPROVAL=true + REQUIRE_PRINCIPAL=true but OPERATOR_PRINCIPALS is empty — on a multi-tenant worker the empty operator set makes isOperator() true-for-all, so every authenticated tenant could read every other tenant's pending-approval queue (GET /v1/approvals & siblings). Set OPERATOR_PRINCIPALS, or unset REQUIRE_PRINCIPAL if this is a single-tenant deployment (#157-① boot invariant)");
+    }
     // 🔴 boot invariant (IMAGE-API-DESIGN.md §P2.4a): the bake door is build-host-RCE-capable, and isOperator([],p)
     // is true-for-all — so enabling bakes with an empty OPERATOR_PRINCIPALS = a WORLD-WRITABLE RCE door. Refuse to
     // start (never a half-open bake door). The explicit-operator gate in server.ts is the runtime twin of this.
@@ -1541,6 +1666,9 @@ export function loadConfig() {
     if (imageBakesEnabled && !Object.values(authTokens).includes(bakeRunnerPrincipal)) {
         throw new Error(`IMAGE_BAKES_ENABLED=true but no SERVICE_AUTH_TOKENS entry maps to the runner principal '${bakeRunnerPrincipal}' — the bake-runner authenticates by its credential (token-derived source), so a '<BAKE_RUNNER_TOKEN>=${bakeRunnerPrincipal}' SERVICE_AUTH_TOKENS entry is required or claim/ingest/heartbeat all 403 (IMAGE-API-DESIGN.md §P2.12 boot invariant)`);
     }
+    // #157 F 类观测:执行车道落点记账放在这里 —— 九域解析与上面全部跨域不变量都过了之后,即「这一轮
+    // 确实启得起来」才成立的位置(写在 REMOTE_EXEC 解析途中的话,后置拒启会留下一条没启起来的落点)。
+    EXEC_LANE_NOTICE = buildExecLaneNotice(orchestration.remoteExec);
     // 平铺面**单点展开**九域产物(唯一存储处),再挂上九个组视图。组视图是对这同一个对象的取景器,
     // 不是第二份拷贝 —— 故 `config.limitsHttp.port === config.port` 恒成立,含热应用之后(见
     // attachConfigGroups / config-types.ts 分组段)。

package/dist/elicitation.d.ts

@@ -15,6 +15,10 @@ export interface ElicitationFrame {
     mode?: "form";
     /** "elicitation_complete" only: how it resolved. */
     action?: McpElicitResponse["action"];
+    /** Server-signed emit timestamp (additive, [2805]§五→[2806]). These side-frames are SERVER-minted — they have
+     *  no core-stream anchor, so no `eventId` (absence is honest, not an omission); this is the frame's own time
+     *  coordinate instead, same posture as the stream-approval frames' `serverNowMs`. */
+    serverNowMs?: number;
 }
 /** The per-run context `onElicit` recovers via ALS. `emit` delivers a frame to the run's live stream;
  *  `abortSignal` (the run's own cancel signal) lets a run-abort promptly cancel an elicitation parked awaiting a

package/dist/elicitation.js

@@ -182,7 +182,7 @@ export class ElicitationCoordinator {
         // cursor (an invisible prompt that then TTL-declines). On a successful emit, charge the per-run-tree budget; a
         // FAILED emit declines (nobody can answer) and must NOT burn maxTotal / the per-server interval.
         try {
-            await ctx.emit({ type: "elicitation", elicitationId: id, mcpServerName: req.server, message, ...(requestedSchema !== undefined ? { requestedSchema } : {}), mode: "form" });
+            await ctx.emit({ type: "elicitation", elicitationId: id, mcpServerName: req.server, message, ...(requestedSchema !== undefined ? { requestedSchema } : {}), mode: "form", serverNowMs: this.now() });
             rc.total += 1;
             rc.lastByServer.set(req.server, t);
         }
@@ -194,7 +194,7 @@ export class ElicitationCoordinator {
         // returning the answer to core (which replies to the MCP server on the still-open connection). Best-effort +
         // ordering-uncritical: the shell already has the answer via respond; a late/lost dismiss is cosmetic.
         void Promise.resolve()
-            .then(() => ctx.emit({ type: "elicitation_complete", elicitationId: id, mcpServerName: req.server, action: answer.action }))
+            .then(() => ctx.emit({ type: "elicitation_complete", elicitationId: id, mcpServerName: req.server, action: answer.action, serverNowMs: this.now() }))
             .catch(() => undefined);
         return answer;
     };

package/dist/http/routes/capabilities.js

@@ -2,6 +2,7 @@ import { DEFAULT_EFFORT_LEVELS } from "@sema-agent/core";
 import { cwdHonored } from "../../task-cwd.js";
 import { mcpInjectionHonored } from "../../task-mcp.js";
 import { sendJson, sendError } from "../send.js";
+import { resolveStreamApprovalGate } from "../../tool-approval.js";
 export async function handleCapabilities(req, res, url, ctx) {
     const miss = { fell: false };
     await handleCapabilitiesBody(req, res, url, ctx, miss);
@@ -211,6 +212,19 @@ async function handleCapabilitiesBody(req, res, url, ctx, miss) {
             // exists, and only fail-closed denies without one ([819]⑤). The durable-approval leg (checkpoint park +
             // /decide) is independent of this.
             toolApproval: Boolean(deps.toolApproval),
+            // #151 车3 刀 3b(设计稿 §2.4):design/172 **流内审批协议**(`approval_request` 呈卡帧 + 开流
+            // preamble 对账基准 + durable 回决端点)。判据走**单一谓词** `resolveStreamApprovalGate` —— 与协调器
+            // 的 askStore 注入、与 `POST /v1/tasks/:taskId/asks/:askId/decision` 的 501 门同一个符号,所以
+            // 「这里说 true」⟺「协议真的在场」是结构成立的,壳不必 trial-by-帧(诚实缺席纪律,同上文各格)。
+            // 五个合取项里最容易被忽略的两条:**账必须是持久的**(local 的 InMemory 形重启即丢已接受的决议)
+            // 与 **park 设施必须在场**(缺席时窗到期没有降级目的地,结局是 core fail-closed deny —— 比现行
+            // 5min 活卡更差,所以协议诚实地不上场、活卡腿逐字保留)。
+            streamApproval: resolveStreamApprovalGate({
+                toolApprovalEnabled: Boolean(deps.toolApproval),
+                streamApprovalEnabled: deps.config.streamApproval?.enabled === true,
+                backend: deps.backend,
+                parkFacility: deps.checkpointStore !== undefined,
+            }).active,
             // [1469] POST /v1/side-query(core 1.361 Runner.sideQuery 包装):一次性 brain 路由问答,无 session
             // 副作用。恒可用(runner 自带)——探测位供壳判「引擎腿在」而非 trial-by-404。
             sideQuery: true,

package/dist/http/routes/runs.d.ts

@@ -22,6 +22,7 @@ export declare const RUN_COMPACT_RE: RegExp;
 export declare const ELICIT_RESPOND_RE: RegExp;
 export declare const QUESTION_RESPOND_RE: RegExp;
 export declare const TOOL_APPROVAL_RESPOND_RE: RegExp;
+export declare const TASK_ASK_DECISION_RE: RegExp;
 export declare const RUN_SUBAGENT_STEER_RE: RegExp;
 export declare const RUN_SUBAGENT_RESUME_RE: RegExp;
 export declare const RUN_SUBAGENT_OUTPUT_RE: RegExp;