@sema-agent/server 7.2.0 → 7.4.0

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

@@ -0,0 +1,84 @@
+/**
+ * #154 件二+件三 —— **装配自证**域:启动期静态自检(拒启判据)与 operator 诊断读面
+ * (`GET /v1/diagnostics/wiring`)。
+ *
+ * 🔴 两件为什么同住一个模块:它们回答的是同一个问题(「这台 worker 到底接了什么线」),只是一个在 boot
+ * 用它拒绝启动、一个在运行期把它读给 operator。分成两处 = 拒启用的判据与诊断报的读数会各自演化,而
+ * 「拒启说没矛盾、诊断页显示矛盾」正是本设计要消灭的那类装配谎言。故 boot 半场是本文件导出的**纯函数**
+ * (可单测、无 I/O),路由半场只是它的读口。
+ *
+ * 分层:本模块不值 import `server.ts`(那条边会闭合运行时装载环),对它只有 `import type`。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { WiringManifest } from "@sema-agent/core";
+import { type StreamApprovalGate, type StreamApprovalGateInput } from "../../tool-approval.js";
+import type { RouteCtx } from "../route-ctx.js";
+/** 流内审批门的读数形:上场即 `"active"`,否则是那五个合取项里**第一个**不满足的原因词
+ *  (与 `resolveStreamApprovalGate` 同一闭集,新增 reason 在此处编译红)。 */
+export type StreamApprovalGateReading = "active" | Extract<StreamApprovalGate, {
+    active: false;
+}>["reason"];
+/** server 自己的装配谓词读数(core 的静态半场之外的那一半:本仓在这台 worker 上做出的判断)。 */
+export interface ServerWiringGates {
+    streamApproval: StreamApprovalGateReading;
+    durableApproval: boolean;
+    checkpointStore: boolean;
+}
+/** `buildServerWiringGates` 的入参 = 三个谓词各自的**真输入**(不接受已算好的布尔:那样这里读到的就
+ *  不再是装配现场的事实,而是别处算完可能已漂的复述)。 */
+export interface ServerWiringGateInput {
+    toolApprovalEnabled: boolean;
+    streamApprovalEnabled: boolean;
+    /** 谓词自己的入参类型(结构形,不 import store 依赖树)—— 取型而非重述,两处不可能漂。 */
+    backend: StreamApprovalGateInput["backend"];
+    /** 在场性即事实;本面不取实例,故 `unknown` 足够(取窄型会把整棵 store 类型树拖进诊断域)。 */
+    checkpointStore: unknown;
+    durableApproval: boolean;
+}
+/** 纯数据产物(`build*`):三个门的当前读数。`streamApproval` 走**单一谓词**
+ *  `resolveStreamApprovalGate` —— 与 `/v1/capabilities` 的 `streamApproval` 位、与回决口的 501 门同一个
+ *  符号,所以诊断页读到的与消费端撞到的行为不可能不同。 */
+export declare function buildServerWiringGates(input: ServerWiringGateInput): ServerWiringGates;
+/** 启动自检的判决:`refusals` 非空 ⇒ 拒启(装配谎言);`warnings` ⇒ 留痕但放行。 */
+export interface StaticWiringAudit {
+    refusals: readonly string[];
+    warnings: readonly string[];
+}
+/** 自检输入 = core 的静态半场 + 我方装配现场的两件事实。 */
+export interface StaticWiringFacts {
+    /** core `describeStaticWiring(deps, specTemplate)` 的产物。 */
+    manifest: WiringManifest;
+    /** 我方喂给 `resolveStreamApprovalGate` 的 `parkFacility` 实参(= checkpoint 店在场 ∧ DURABLE_APPROVAL)。 */
+    parkFacility: boolean;
+    /** store backend 的种类;`undefined` = env-only worker(无 backend)。 */
+    backendKind: "mysql" | "pg" | "local" | undefined;
+}
+/**
+ * 三项对表(设计稿件二)。判据全是**两个独立谓词对同一件事的答案**,矛盾即装配谎言 —— 装配谎言不是
+ * 「配置不理想」,是「服务端对自己接了什么线的两套说法互斥」,继续启动只会把矛盾带进运行期的每一条腿。
+ *
+ *  ① park 设施:core 从 `spec.checkpointStore ?? deps.checkpointStore` 判 `parkLane.capable`,我方从
+ *     `backend.checkpoint ∧ DURABLE_APPROVAL` 判 `parkFacility` 并据此决定流内审批协议上不上场。两者
+ *     不等 ⇒ 协议按「窗到期能 park」上场而引擎侧根本不 park(结局是 core fail-closed deny),或反之
+ *     白白关掉一个可用的协议。`capable` 真而 `effective` 不真同样致命:能力在、这条部署形上却不会真的
+ *     park,窗到期依旧无降级目的地。
+ *  ② 会话店持久性:manifest 声明 `declared_durable` 而后端是 local / 根本没有后端 ⇒ 「重启存活」的声明
+ *     没有介质兑现。这条与 memory+durable 两条既有拒启同族(声明与介质必须对得上)。
+ *  ③ interaction posture 声明 `interactive` 却没有任何 question 投递面 ⇒ 只 **warn**:core 在 prepare 时
+ *     会按腿拒,boot 先一步把话说成人话。不拒启,因为部署形本身可能只是暂时没接活体面,而 core 侧已有
+ *     兜底门 —— 拒启会把一个可运行的部署挡在门外。
+ *  ④ park 车道的持久性读数不可信时 ⇒ **warn**(理由与这条判据为什么不是拒启,见其行内注)。
+ *
+ * 判决分两级是有判据的:**拒启**留给「两个谓词对同一件事互斥」(其中一个必错,继续跑就是带着谎言服务);
+ * **警告**留给「读数不可信/声明不完整」(信号本身还不足以断定谁错,据此拒启会挡住正常部署)。
+ */
+export declare function buildStaticWiringAudit(facts: StaticWiringFacts): StaticWiringAudit;
+/**
+ * boot 消费口:`refusals` 非空即抛(拒启,与 memory+durable 两条既有拒启同族的 fail-loud 形),
+ * `warnings` 逐条 warn。返回判决本体,调用方可以继续把读数打进启动 info 行。
+ */
+export declare function assertStaticWiringConsistent(facts: StaticWiringFacts, logger: {
+    warn: (msg: string, meta?: Record<string, unknown>) => void;
+} | undefined): StaticWiringAudit;
+export declare function handleDiagnostics(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/http/routes/diagnostics.js

@@ -0,0 +1,140 @@
+import { resolveStreamApprovalGate } from "../../tool-approval.js";
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+/** 纯数据产物(`build*`):三个门的当前读数。`streamApproval` 走**单一谓词**
+ *  `resolveStreamApprovalGate` —— 与 `/v1/capabilities` 的 `streamApproval` 位、与回决口的 501 门同一个
+ *  符号,所以诊断页读到的与消费端撞到的行为不可能不同。 */
+export function buildServerWiringGates(input) {
+    const gate = resolveStreamApprovalGate({
+        toolApprovalEnabled: input.toolApprovalEnabled,
+        streamApprovalEnabled: input.streamApprovalEnabled,
+        backend: input.backend,
+        parkFacility: input.checkpointStore !== undefined,
+    });
+    return {
+        streamApproval: gate.active ? "active" : gate.reason,
+        durableApproval: input.durableApproval,
+        checkpointStore: input.checkpointStore !== undefined,
+    };
+}
+/**
+ * 三项对表(设计稿件二)。判据全是**两个独立谓词对同一件事的答案**,矛盾即装配谎言 —— 装配谎言不是
+ * 「配置不理想」,是「服务端对自己接了什么线的两套说法互斥」,继续启动只会把矛盾带进运行期的每一条腿。
+ *
+ *  ① park 设施:core 从 `spec.checkpointStore ?? deps.checkpointStore` 判 `parkLane.capable`,我方从
+ *     `backend.checkpoint ∧ DURABLE_APPROVAL` 判 `parkFacility` 并据此决定流内审批协议上不上场。两者
+ *     不等 ⇒ 协议按「窗到期能 park」上场而引擎侧根本不 park(结局是 core fail-closed deny),或反之
+ *     白白关掉一个可用的协议。`capable` 真而 `effective` 不真同样致命:能力在、这条部署形上却不会真的
+ *     park,窗到期依旧无降级目的地。
+ *  ② 会话店持久性:manifest 声明 `declared_durable` 而后端是 local / 根本没有后端 ⇒ 「重启存活」的声明
+ *     没有介质兑现。这条与 memory+durable 两条既有拒启同族(声明与介质必须对得上)。
+ *  ③ interaction posture 声明 `interactive` 却没有任何 question 投递面 ⇒ 只 **warn**:core 在 prepare 时
+ *     会按腿拒,boot 先一步把话说成人话。不拒启,因为部署形本身可能只是暂时没接活体面,而 core 侧已有
+ *     兜底门 —— 拒启会把一个可运行的部署挡在门外。
+ *  ④ park 车道的持久性读数不可信时 ⇒ **warn**(理由与这条判据为什么不是拒启,见其行内注)。
+ *
+ * 判决分两级是有判据的:**拒启**留给「两个谓词对同一件事互斥」(其中一个必错,继续跑就是带着谎言服务);
+ * **警告**留给「读数不可信/声明不完整」(信号本身还不足以断定谁错,据此拒启会挡住正常部署)。
+ */
+export function buildStaticWiringAudit(facts) {
+    const refusals = [];
+    const warnings = [];
+    const park = facts.manifest.parkLane;
+    if (park.capable !== facts.parkFacility) {
+        refusals.push(`park facility contradiction: the engine's static wiring says parkLane.capable=${park.capable} while this server assembled its approval gates with parkFacility=${facts.parkFacility}. ` +
+            `One of the two is wrong about the same checkpoint store — refusing to start rather than serving a worker whose approval lane can silently fail closed. ` +
+            `Check DURABLE_APPROVAL and the backend's checkpoint face (they are what both predicates read).`);
+    }
+    else if (facts.parkFacility && park.effective !== true) {
+        refusals.push(`park facility contradiction: this server assembled its approval gates with parkFacility=true, but the engine's static wiring resolves parkLane.effective=${JSON.stringify(park.effective)} (reasons: ${park.reasons.join(", ") || "none"}). ` +
+            `A window expiry would then have no degradation target and adjudicate as a fail-closed deny — refusing to start.`);
+    }
+    // 判据写成「不在持久集合里」而不是「是 local」是有方向的:将来多一种 backend kind 时,它会**拒启**
+    // 直到有人显式把它判进持久集,而不是静默通过 —— 声明与介质的对表,失败方向必须朝拒绝那边。
+    if (facts.manifest.session.store === "declared_durable" && facts.backendKind !== "mysql" && facts.backendKind !== "pg") {
+        refusals.push(`session store durability contradiction: the engine's static wiring reports session.store="declared_durable" while the store backend is ${facts.backendKind === undefined ? "absent (env-only worker)" : `"${facts.backendKind}"`}. ` +
+            `A durable declaration with no durable medium is a claim nothing can honor — refusing to start. Wire DB_BACKEND=mysql|pg, or fix the store's durability declaration.`);
+    }
+    // park 车道的**持久性读数**(codex 交叉复审 2026-08-07 R2-F2,验真后部分采纳)。`capable` 说的是
+    // 「有没有 checkpoint 店」、`effective` 说的是「这条部署形会不会真 park」—— 两者都为真时仍可能是一个
+    // 重启即丢的店,那样窗到期后被 park 的审批在重启后无法赎回,而流内审批协议正是拿 park 当降级目的地。
+    // 🔴 为什么是 **warn 而不是拒启**:本仓的 SQL/local checkpoint 店**都还没有 `durability` 声明**,core
+    // 因此对每一个真持久部署都读出 `process_local`。据此拒启会拿一个不可信信号挡住 100% 的现存 durable
+    // 部署 —— 那不是查出矛盾。根治在店侧补声明;在那之前,把「这个读数不可信」响亮说出来,不静默。
+    if (facts.parkFacility && facts.manifest.parkLane.checkpointDurability !== "declared_durable") {
+        warnings.push(`park facility is enabled but the checkpoint store does not declare durable storage ` +
+            `(parkLane.checkpointDurability=${JSON.stringify(facts.manifest.parkLane.checkpointDurability ?? null)}). ` +
+            `A parked approval survives a restart only on a durable store — and the in-tree checkpoint adapters currently declare no durability at all, so this reading cannot yet distinguish "really process-local" from "nobody declared it". ` +
+            `Treat park-lane recovery as unproven until the adapter declares its durability.`);
+    }
+    if (facts.manifest.interaction.posture === "interactive" && facts.manifest.question.wired !== "wired") {
+        warnings.push(`interactionPosture declares "interactive" but no question delivery face is wired (question.wired=${JSON.stringify(facts.manifest.question.wired)}) — ` +
+            `every leg that asks a question will be refused by the engine at prepare time. Wire the live question seam (ASK_QUESTION_ENABLED), or declare the headless posture.`);
+    }
+    return { refusals, warnings };
+}
+/**
+ * boot 消费口:`refusals` 非空即抛(拒启,与 memory+durable 两条既有拒启同族的 fail-loud 形),
+ * `warnings` 逐条 warn。返回判决本体,调用方可以继续把读数打进启动 info 行。
+ */
+export function assertStaticWiringConsistent(facts, logger) {
+    const audit = buildStaticWiringAudit(facts);
+    for (const w of audit.warnings)
+        logger?.warn("wiring_static_warning", { detail: w });
+    if (audit.refusals.length > 0) {
+        throw new Error(`static wiring self-check failed — refusing to start:\n${audit.refusals.map((r) => `  · ${r}`).join("\n")}`);
+    }
+    return audit;
+}
+export async function handleDiagnostics(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleDiagnosticsBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleDiagnosticsBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    // 件三:「这台 worker 到底接了什么线」一屏看清 = core 的静态半场(含 `governance` 段 —— 本面**就是**
+    // 那个段的 operator 受众)+ server 自己三个装配谓词的读数。
+    //
+    // 门 = `explicitOperatorOk`(**不是** `isOperator`)。执法条件是**名单在场 ∨ 多租户**,不是只看
+    // `REQUIRE_PRINCIPAL`:本件的 SSE 腿对同一段 governance 恒判 `explicitOperatorOk`,若这里只在
+    // REQUIRE_PRINCIPAL 时判,「列了 operator 名单却没开 REQUIRE_PRINCIPAL」的部署上就成了流里关着、
+    // 端点上开着 —— 一个秘密两套门,严的那道白严(codex 交叉复审 2026-08-07 R2-F1,验真后采纳)。
+    // 名单为空 ∧ 非多租户 = 单租户 turnkey:该部署没有 operator 这个概念,唯一的用户就是 operator,
+    // 边界由全局 service-credential 门把守(与 `GET /v1/outcomes` 同裁)。
+    // 401 由更上游的全局门给出,本域只判 operator 与否。
+    //
+    // ⚠️ 与 SSE 腿的**残余不对称**(显式裁定,不是疏忽):turnkey 形上流里仍然谁都拿不到治理段,而本端点
+    // 给。理由=流是多订阅面且身份来自连接、端点是一次显式的 operator 请求;失败方向因此在流那侧更严。
+    //
+    // **不含** per-leg effective 历史:治理段只存在于 live 帧的 operator 投影里,durable 账本恒存剥后形
+    // (账本写时不知道未来读者是谁)。历史考古是另一件事,不在本面伪装成有。
+    if (req.method === "GET" && url === "/v1/diagnostics/wiring") {
+        if (deps.config.operatorPrincipals.length > 0 || deps.config.requirePrincipal) {
+            const principal = gatedPrincipal(req, deps.config);
+            if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
+                sendError(res, 403, "auth.operator_only", "wiring diagnostics are operator-only on a multi-tenant worker");
+                return;
+            }
+        }
+        // 静态半场是 **composition root 在 boot 算的**(与拒启自检同一份产物,不可能与它不同)。缺席 ⇒ 这个
+        // 进程不是由 main.ts 装起来的(测试夹具形),此面诚实地不存在 —— 落到全局 404,而不是回一个空壳 200。
+        if (!deps.staticWiring) {
+            miss.fell = true;
+            return;
+        }
+        sendJson(res, 200, {
+            static: deps.staticWiring,
+            serverGates: buildServerWiringGates({
+                toolApprovalEnabled: deps.toolApproval !== undefined,
+                streamApprovalEnabled: deps.config.streamApproval?.enabled === true,
+                backend: deps.backend,
+                checkpointStore: deps.checkpointStore,
+                durableApproval: deps.config.durableApproval === true,
+            }),
+        });
+        return;
+    }
+    miss.fell = true;
+}
+//# sourceMappingURL=diagnostics.js.map

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;