@sema-agent/server 7.131.0 → 7.133.0

package/dist/http/principal-gate.js

@@ -1,5 +1,5 @@
 import { timingSafeEqual } from "node:crypto";
-import { PRINCIPAL_TOKEN_HEADER, verifiedPrincipal, ssoVerifiedPrincipal } from "../security.js";
+import { PRINCIPAL_TOKEN_HEADER, verifiedPrincipal, ssoVerifiedPrincipal, ownerlessRowOpen, mintPrincipal } from "../security.js";
 import { sendError } from "./send.js";
 export function headerStr(v) {
     return Array.isArray(v) ? v[0] : v;
@@ -50,7 +50,8 @@ export function verifiedIdentitySource(req, config) {
 export function gatedPrincipal(req, config) {
     if (bearerPresentedButUnverified(req, config))
         return undefined;
-    return verifiedPrincipal(req, config);
+    const verified = verifiedPrincipal(req, config);
+    return verified === undefined ? undefined : mintPrincipal(verified);
 }
 export function principalTokenPresentedButUnverified(req, config) {
     if (!config.directDoorActive)
@@ -86,29 +87,74 @@ export function sendUnauthorized(res, face) {
         }
     }
 }
+function sameIdentity(principal, owner) {
+    return principal === owner;
+}
 export function runOwnerReadable(principal, owner, config) {
     if (owner === null)
         return true;
-    if (principal === owner)
+    if (principal !== undefined && sameIdentity(principal, owner))
         return true;
     return !config.requirePrincipal && owner === "anon:shell-live" && principal === undefined;
 }
-export function devOpenDeployment(config) {
-    const anyServiceToken = Boolean(config.authToken) || Object.keys(config.authTokens ?? {}).length > 0;
-    return !anyServiceToken && !config.traceToken && !config.requirePrincipal;
+export function hasServiceAuth(config) {
+    return Boolean(config.authToken) || Object.keys(config.authTokens ?? {}).length > 0;
+}
+function identitySourceWired(kind, w) {
+    switch (kind) {
+        case "service_token":
+            return hasServiceAuth(w.config);
+        case "sso":
+            return w.webAdminJwtVerifier !== undefined;
+        case "direct_door_jwt":
+            return w.config.directDoorActive;
+        default: {
+            const unknownKind = kind;
+            throw new Error(`identity sources: unknown identity source ${String(unknownKind)}`);
+        }
+    }
 }
-export function sessionOwnerReadable(principal, owner, config) {
-    return devOpenDeployment(config) || runOwnerReadable(principal, owner, config);
+export function wiredIdentitySources(w) {
+    return IDENTITY_SOURCES.filter((k) => identitySourceWired(k, w));
 }
-export function explicitOperatorOk(principal, operatorPrincipals) {
-    return operatorPrincipals.length > 0 && principal !== undefined && operatorPrincipals.includes(principal);
+export function devOpenDeployment(w) {
+    return wiredIdentitySources(w).length === 0 && !w.config.traceToken && !w.config.requirePrincipal;
 }
-export function sendOperatorPrincipalsRequired(res) {
-    sendError(res, 501, "capability.operator_principals_required", "this endpoint is operator-only and OPERATOR_PRINCIPALS is empty, so no caller can be an operator on this deployment; configure OPERATOR_PRINCIPALS to enable it");
+export function sessionCallerOf(req, w) {
+    const principal = gatedPrincipal(req, w.config);
+    return { principal, fleet: devOpenDeployment(w) || (principal === undefined && systemFor(req, w.config) !== undefined) };
+}
+export function sessionOwnerReadable(caller, cell, w) {
+    if (devOpenDeployment(w))
+        return true;
+    if (cell.owner === null)
+        return ownerlessRowOpen(cell, caller);
+    return runOwnerReadable(caller.principal, cell.owner, w.config);
 }
-export function isOperator(principal, operatorPrincipals) {
-    if (operatorPrincipals.length === 0)
+export function explicitOperatorOk(principal, roster) {
+    if (roster.operatorSingleUser === true)
         return true;
-    return principal !== undefined && operatorPrincipals.includes(principal);
+    return roster.operatorPrincipals.length > 0 && principal !== undefined && roster.operatorPrincipals.includes(principal);
+}
+export function operatorRosterPresent(roster) {
+    return roster.operatorSingleUser === true || roster.operatorPrincipals.length > 0;
+}
+export function buildOperatorUndeclaredNotice(config, approvalFaceWired) {
+    if (config.requirePrincipal === true || operatorRosterPresent(config) || !approvalFaceWired)
+        return undefined;
+    return {
+        event: "operator_undeclared_single_user",
+        fields: {
+            detail: "this single-user deployment declares no operator: OPERATOR_PRINCIPALS is empty and OPERATOR_SINGLE_USER is not set, so no caller is an operator — " +
+                "GET /v1/approvals, its stream, /v1/assistant/inbox and /v1/assistant/tasks show each caller only its own pending approvals (a caller that sends no principal sees none) and ignore ?owner=. " +
+                "To act as this deployment's operator, add one line: OPERATOR_SINGLE_USER=true",
+        },
+    };
+}
+export function sendOperatorPrincipalsRequired(res) {
+    sendError(res, 501, "capability.operator_principals_required", `this endpoint is operator-only and this deployment has no operator roster (OPERATOR_PRINCIPALS is empty and OPERATOR_SINGLE_USER is not declared), so no caller can be an operator; ${buildOperatorRosterWayOut()}`);
+}
+export function buildOperatorRosterWayOut() {
+    return "configure OPERATOR_PRINCIPALS with the named operator principals, or — on a single-user deployment (REQUIRE_PRINCIPAL off) — declare OPERATOR_SINGLE_USER=true";
 }
 //# sourceMappingURL=principal-gate.js.map

package/dist/http/readiness.d.ts

@@ -23,6 +23,7 @@
  */
 import type { ServerResponse } from "node:http";
 import type { ServingLeaseView } from "../fleet/engine-signal.js";
+import { type RefusalBody } from "./refusal-body.js";
 /**
  * 就绪原因闭集,**数组序 = 优先序**:`/health.readyReason` 取首条的句、计费门取首条的拒绝码。
  * draining 在前 —— 一台正在下线的副本「去找替补」(Retry-After 15)比「稍后重试本机」(5)更对。
@@ -86,11 +87,8 @@ export declare function admissionRefusalOf(verdict: ReadinessVerdict, lease: Ser
  *  `{status, body}` 的赎回席只取体(它的路由刻意不带头,见 `approval-sweeps.ts` 该臂注)。 */
 export interface BillableRefusal {
     readonly status: 503;
-    readonly body: {
-        readonly error: string;
-        readonly errorCode: string;
-        readonly message: string;
-    };
+    /** `error` 是冻结的词(`draining` / `model_roster_pending` / `lease_expired`),`message` 是给人读的句子(机读事实里的一键)。 */
+    readonly body: RefusalBody;
     readonly retryAfterSec: 15 | 5 | 60;
 }
 /**
@@ -100,6 +98,14 @@ export interface BillableRefusal {
  * 停机因由声明口一起退役(排空口的体改成契约 `DrainRequest`,没有因由字段);`lease_expired` 一臂新增。
  */
 export declare function billableRefusalOf(reason: AdmissionRefusal): BillableRefusal;
+/**
+ * 订阅面终帧要的 `{ errorCode, message }` —— 与提交面 503 体**同一只铸点**的产物:`errorCode` 是体的码,`message` 是体里 `message` 键的那句话(`error` 是冻结的词,
+ * 句子在 `message`)。从体里读,不另抄一份;体里没有那句话是铸点坏了 ⇒ 响亮抛(不静默发一帧没有句子的终帧)。
+ */
+export declare function billableRefusalFrame(refusal: BillableRefusal): {
+    readonly errorCode: string;
+    readonly message: string;
+};
 /** 发送形:`Retry-After` + 体(`dispatch.ts` 的 billable 门与 a2a `message/send` 同调)。走 `sendError` —— errorCode
  *  是它的必填位置参(对抗复审 #3:修前这里是 `sendJson(res, r.status, r.body)`,与 leader 口的豁免行逐字同文,
  *  在 error-code-key-gate 上借了别人的豁免过门);体键序与修前逐字同(`error, errorCode, message, reason?`)。 */

package/dist/http/readiness.js

@@ -1,4 +1,5 @@
 import { sendJson, sendError } from "./send.js";
+import { refusalBody } from "./refusal-body.js";
 export const READINESS_REASONS = ["draining", "model_roster_pending"];
 export function readinessOf(deps) {
     const [first, ...rest] = READINESS_REASONS.filter((r) => holds(r, deps));
@@ -60,17 +61,23 @@ export function admissionRefusalOf(verdict, lease, kind) {
 export function billableRefusalOf(reason) {
     switch (reason) {
         case "draining":
-            return { status: 503, body: { error: "draining", errorCode: "draining", message: "this instance is draining for shutdown/upgrade — retry against the replacement instance" }, retryAfterSec: 15 };
+            return { status: 503, body: refusalBody({ errorCode: "draining", message: "draining", facts: { message: "this instance is draining for shutdown/upgrade — retry against the replacement instance" } }), retryAfterSec: 15 };
         case "model_roster_pending":
-            return { status: 503, body: { error: "model_roster_pending", errorCode: "state.model_roster_pending", message: "this worker has no model yet (waiting for the first effective-config pull to land the roster) — retry shortly" }, retryAfterSec: 5 };
+            return { status: 503, body: refusalBody({ errorCode: "state.model_roster_pending", message: "model_roster_pending", facts: { message: "this worker has no model yet (waiting for the first effective-config pull to land the roster) — retry shortly" } }), retryAfterSec: 5 };
         case "lease_expired":
-            return { status: 503, body: { error: "lease_expired", errorCode: "state.lease_expired", message: "this instance has not renewed its serving lease with the fleet center for longer than its outage limit — it takes no new work; cancel, approvals, resume and reads stay open here — retry new work against another instance" }, retryAfterSec: 60 };
+            return { status: 503, body: refusalBody({ errorCode: "state.lease_expired", message: "lease_expired", facts: { message: "this instance has not renewed its serving lease with the fleet center for longer than its outage limit — it takes no new work; cancel, approvals, resume and reads stay open here — retry new work against another instance" } }), retryAfterSec: 60 };
         default: {
             const unhandled = reason;
             throw new Error(`admission refusal without a billable refusal: ${String(unhandled)}`);
         }
     }
 }
+export function billableRefusalFrame(refusal) {
+    const message = refusal.body["message"];
+    if (typeof message !== "string")
+        throw new Error(`billable refusal body without its message sentence: ${refusal.body.errorCode}`);
+    return { errorCode: refusal.body.errorCode, message };
+}
 export function sendBillableRefusal(res, refusal) {
     const { error, errorCode, ...extra } = refusal.body;
     res.setHeader("retry-after", String(refusal.retryAfterSec));

package/dist/http/refusal-body.d.ts

@@ -0,0 +1,21 @@
+/**
+ * **全仓唯一的拒体组句器**(零依赖叶子模块 —— `http/checkpoint-ctx.ts` 的续跑折叠也读它,而那个模块经编译产物进随包排空脚本,闭包只许 node 内建 / 引擎包根)。
+ *
+ * 一只拒 = 三件事:机读码、给人读的句子、拒的机读事实(`field` / `reason` / `count` / `cap` / `detail` …;缺席 = 没有可机读的事实)。
+ * 拒体 = `{ error, errorCode, ...facts }`(机读事实原样随体、排在最后)。整面拒(`http/send.ts` 的 `sendError` / `sendHttpError`)、把同一只拒当**数据**带进 200 体的面板
+ * (`GET /v1/sessions/:id/mcp` 的 `scenarioRefusal`)、续跑把一只拒折成 409 的 `resume_blocked_by_policy`(`http/checkpoint-ctx.ts`)读的都是它 —— 同一只拒在几处渲出的成员逐字同。
+ * 判据只交这份数据,不自己拼体。
+ */
+export interface Refusal {
+    readonly errorCode: string;
+    readonly message: string;
+    readonly facts?: Readonly<Record<string, unknown>>;
+}
+/** {@link refusalBody} 的产物形:`error` + `errorCode` 恒在,机读事实随后。 */
+export type RefusalBody = {
+    readonly error: string;
+    readonly errorCode: string;
+} & Record<string, unknown>;
+/** 拒体:`{ error, errorCode, ...facts }`。 */
+export declare function refusalBody(r: Refusal): RefusalBody;
+//# sourceMappingURL=refusal-body.d.ts.map

package/dist/http/refusal-body.js

@@ -0,0 +1,4 @@
+export function refusalBody(r) {
+    return { error: r.message, errorCode: r.errorCode, ...r.facts };
+}
+//# sourceMappingURL=refusal-body.js.map

package/dist/http/request-guards.d.ts

@@ -4,21 +4,52 @@
  * ctx 字段 1 只(`deps`):本族对外围的耦合就这一格,它也是这一族的可测性读数。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { type SessionOwnerCell } from "../security.js";
+import { type RefusalBody } from "./refusal-body.js";
 import type { FlatServiceDeps } from "./server.js";
 import type { LeaseRefusalAdmission } from "../fleet-lease.js";
 import { type QuotaDecision } from "../observability/cost-quota.js";
+import { type SqlWallSource, type SqlWallsReading } from "../plugins/sql-driver.js";
+/**
+ * 受理口对一份提交体的库墙判决:被哪一堵墙拒、量到多少、门限多少。提交体要整只落进库 —— 会话日志的用户消息、durable 审批部署上的续跑输入 ——
+ * 所以每堵墙各量各的、**量的是店真正发出去的东西**,`null` 的墙不参与(PG 两堵都是 `null`;InnoDB 的行墙是 `null`、包墙在;TiDB 两堵都在):
+ *  · `row` —— 行里存的是体的**原字节**(不转义):体的 JSON 字节 ≤ `rowWallPayloadBytes(行墙, "json")`(行墙 − JSON 行的行内余量);
+ *  · `packet` —— 体经 mysql2 以一只字符串字面进语句,`" ' \` 与控制字符各多一个反斜杠字节:**转义后的语句字节**
+ *    (`escapedStatementBytes`,镜像被钉在 mysql2 自己的 `escape` 上)≤ `packetWallStatementBytes(包墙)`(包墙 − 语句余量)。提交体按原样进语句、
+ *    没有 blob 十六进制字面的 2× 膨胀,所以不折半;但引号 / 反斜杠密集的体会比自己的字节数长(至多 2×),这正是不能量原字节的原因。
+ * 两腿的折算与 SQL 快照 blob 的缺省帽读同一份(`plugins/sql-driver.ts`,余量各只在那里定义一次)。两腿都拒时报行墙那条(行墙句逐字沿用)。
+ * 入参是**已判好的墙**(`sql-driver.ts` `sqlWallsOf` —— 事实缺席时的落点只在那里定义,与 blob 帽同一只判官、同一个方向);本函数不读事实、不判缺席,
+ * 墙从哪来(`sources` 里**被拒的那一堵**的出处)原样带进判决(`wallSource`),拒句按它分两形:库报的墙点名库的上限与旋钮,假定的墙(事实还没建立,或事实在场但这一堵读失败、退了文档缺省)只说「库的这个上限没读到、按最保守的墙拒」。
+ *
+ * 🔴 **包墙腿是同一只规则的提前一跑,不是第二套规则**(S-1746 主会话裁定):包墙是物理连接的事实(会话值,连接建立时从全局拷一份、此后不变),
+ * 终判在将要执行写入的那条连接上 —— 那是库自己(续跑输入那一笔被拒 ⇒ 店的带码拒 ⇒ 同一个 413;会话日志那一笔走它既有的失败面);SQL 快照 blob 则由
+ * `blob-backend.ts` 经 `connectJudged` 在写入连接上判。受理时手里没有那条连接,判官 `sqlWallsOf` 读的 `facts` 是池里**最近一次初始化**的那条连接的读数
+ * (`SqlDriver.facts`:池见过的最新读数,只在有连接初始化时才更新),同一个折算 `packetWallStatementBytes`:拒 ⇒ 413 在任何副作用之前;收 ⇒ 写入那条连接上的判决仍是终判。
+ * 这个读数是**缓存**,DBA 调了全局值之后、下一条连接初始化之前,它与库此刻的值两个方向都可能不一致:调大 ⇒ 受理口仍按旧的小值拒(新墙本装得下的体也 413,
+ * 直到有连接按新值初始化 —— 快照 blob 的旧连接自换就会带来一条);调小 ⇒ 受理口按旧的大值放行,写入那条连接上的库再拒(续跑输入那一笔 = 同一个 413)。
+ * 两堵墙都不存在(PG / 没有 SQL 后端)⇒ `null`。一堵墙「够不着」(行墙门限 ≥ 请求体上限;包墙门限 ≥ 请求体上限的 2×,即转义上界也到不了)时那一腿不量,
+ * 两腿都够不着就连 `JSON.stringify` 都不调 —— 默认的 PG / MySQL 8(包墙 64 MiB)/ 无 SQL 后端部署零额外开销。
+ * 受理口(`admission.ts` `prepareSpec`)按它答 413 `request.payload_too_large`,句子按 `by` × `wallSource` 点名真正拒绝的那堵墙;两位都是闭集,加一臂 = 编译红。
+ */
+export interface SubmitBodyRefusal {
+    readonly by: "row" | "packet";
+    /** 这一腿量到的字节:`row` = 体的 JSON 字节;`packet` = 转义后的语句字节。 */
+    readonly bytes: number;
+    /** 这一腿的门限(同单位)。 */
+    readonly limitBytes: number;
+    /** 拒它的那堵墙(`maxRowBytes` / `maxPacketBytes`),进句子。 */
+    readonly wallBytes: number;
+    /** 拒它的那堵墙从哪来(`sqlWallsOf` 读数 `sources` 里同一堵的出处;上 wire 为拒体的 `wallSource`):`reported` = 库自己报的;`assumed` = 不是库报的(事实还没建立,或这一堵读失败、退了文档缺省)。 */
+    readonly wallSource: SqlWallSource;
+}
+export declare function refuseSubmitBody(walls: SqlWallsReading, body: unknown): SubmitBodyRefusal | null;
 /**
  * S-866 ③ —— 租约拒绝的应答形({@link leaseRefusalOf} 的产物;`{status, body}` 交回形 + 镜像头用的 `retryAfterSec`)。
- * 体键序固定 `error, errorCode, …`(冻结门 `FROZEN_RESULT_BODY` 按这个字面形锚)。
+ * 体经唯一组句器铸(键序 `error, errorCode, …机读位`;冻结门 `FROZEN_RESULT_BODY` 读 `refusalBody({ errorCode, message, … })` 这一形)。
  */
 export interface LeaseRefusal {
     readonly status: 429 | 503;
-    readonly body: {
-        readonly error: string;
-        readonly errorCode: string;
-        readonly retryAfterSec: number;
-        readonly [extra: string]: unknown;
-    };
+    readonly body: RefusalBody;
     readonly retryAfterSec: number;
 }
 /**
@@ -33,20 +64,13 @@ export interface LeaseRefusal {
 export declare function leaseRefusalOf(adm: LeaseRefusalAdmission): LeaseRefusal;
 /**
  * 成本配额越顶 → 429 `limit.cost_quota_exceeded` 的**唯一**体铸点(三只门同调:路由门 `quotaExceeded`、属主门
- * `ownerCostQuotaDenied`、赎回席 `approval-sweeps.ts`;修前三份手抄)。体键序 `error, errorCode, …`(冻结门
- * `FROZEN_RESULT_BODY` 按这个字面形锚)。`retryAfterSec` 与 `windowResetsAt` 同源于决策的 `windowEndsAtMs`
+ * `ownerCostQuotaDenied`、赎回席 `approval-sweeps.ts`;修前三份手抄)。体经唯一组句器铸(键序 `error, errorCode, …机读位`;冻结门
+ * `FROZEN_RESULT_BODY` 读 `refusalBody({ errorCode, message, … })` 这一形)。`retryAfterSec` 与 `windowResetsAt` 同源于决策的 `windowEndsAtMs`
  * (同一次读钟),`Retry-After` 头由各发送点从体里的 `retryAfterSec` 镜像。
  */
 export declare function costQuotaRefusalOf(d: QuotaDecision): {
     status: 429;
-    body: {
-        error: string;
-        errorCode: string;
-        usedMicroUsd: number;
-        limitMicroUsd: number;
-        retryAfterSec: number;
-        windowResetsAt: string;
-    };
+    body: RefusalBody;
 };
 export declare function createRequestGuards(ctx: {
     deps: FlatServiceDeps;
@@ -65,11 +89,7 @@ export declare function createRequestGuards(ctx: {
     leaseDenied: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
     usageWindowDenialFor: (key: string) => Promise<{
         status: number;
-        body: {
-            error: string;
-            errorCode: string;
-            retryAfterSec: number;
-        };
+        body: RefusalBody;
         retryAfterSec: number;
     } | undefined>;
     usageWindowDenied: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
@@ -85,7 +105,7 @@ export declare function createRequestGuards(ctx: {
         gateOwner: string | null;
     };
     runOwnerOk: (req: IncomingMessage, res: ServerResponse, owner: string | null) => boolean;
-    sessionOwnerOk: (req: IncomingMessage, res: ServerResponse, owner: string | null) => boolean;
+    sessionOwnerOk: (req: IncomingMessage, res: ServerResponse, cell: SessionOwnerCell) => boolean;
     runSessionAcceptOk: (req: IncomingMessage, res: ServerResponse, run: {
         sessionId: string | null;
     }, face: string, notFoundError?: string) => boolean;

package/dist/http/request-guards.js

@@ -1,18 +1,46 @@
 import { GLOBAL_USAGE_KEY, usageRetryAfterMs } from "@sema-agent/core";
-import { HttpError, principalFrom } from "../security.js";
+import { createCodedHttpError, principalFrom } from "../security.js";
 import { RUN_NOT_FOUND_MESSAGE, SESSION_NOT_FOUND_MESSAGE } from "./route-ctx.js";
-import { sendError } from "./send.js";
-import { authorized, systemFor, gatedPrincipal, explicitOperatorOk, runOwnerReadable, sessionOwnerReadable, devOpenDeployment, sendPrincipalRefusal } from "./principal-gate.js";
+import { invalidJsonError, sendError } from "./send.js";
+import { refusalBody } from "./refusal-body.js";
+import { limitFactsUnmeasured } from "../limit-refusal.js";
+import { authorized, systemFor, gatedPrincipal, explicitOperatorOk, sessionOwnerReadable, sessionCallerOf, devOpenDeployment, sendPrincipalRefusal } from "./principal-gate.js";
+import { runRowReadable } from "./owner-access.js";
 import { quotaWindowResetsAt } from "../observability/cost-quota.js";
+import { escapedStatementBytes, packetWallStatementBytes, rowWallPayloadBytes } from "../plugins/sql-driver.js";
 const MAX_BODY = 8 * 1024 * 1024;
+export function refuseSubmitBody(walls, body) {
+    const rowWall = walls.maxRowBytes;
+    const packetWall = walls.maxPacketBytes;
+    const row = rowWall === null ? null : { wallBytes: rowWall, limitBytes: rowWallPayloadBytes(rowWall, "json") };
+    const packet = packetWall === null ? null : { wallBytes: packetWall, limitBytes: packetWallStatementBytes(packetWall) };
+    const liveRow = row !== null && row.limitBytes < MAX_BODY ? row : null;
+    const livePacket = packet !== null && packet.limitBytes < 2 * MAX_BODY ? packet : null;
+    if (liveRow === null && livePacket === null)
+        return null;
+    const json = JSON.stringify(body);
+    const jsonBytes = Buffer.byteLength(json, "utf8");
+    if (liveRow !== null && jsonBytes > liveRow.limitBytes)
+        return { by: "row", bytes: jsonBytes, ...liveRow, wallSource: walls.sources.maxRowBytes };
+    if (livePacket !== null && jsonBytes * 2 > livePacket.limitBytes) {
+        const sentBytes = escapedStatementBytes(json);
+        if (sentBytes > livePacket.limitBytes)
+            return { by: "packet", bytes: sentBytes, ...livePacket, wallSource: walls.sources.maxPacketBytes };
+    }
+    return null;
+}
 export function leaseRefusalOf(adm) {
     switch (adm.reason) {
         case "budget_exhausted":
-            return { status: 429, body: { error: "budget exhausted (quota lease)", errorCode: "quota_exhausted", retryAfterSec: adm.retryAfterSec, ...(adm.detail ?? {}) }, retryAfterSec: adm.retryAfterSec };
+            return { status: 429, body: refusalBody({ errorCode: "quota_exhausted", message: "budget exhausted (quota lease)", facts: { retryAfterSec: adm.retryAfterSec, ...(adm.detail ?? {}) } }), retryAfterSec: adm.retryAfterSec };
         case "lease_unavailable":
             return {
                 status: 503,
-                body: { error: "quota lease unavailable — this deployment enforces budgets fail-closed and could not confirm this caller's budget with the quota center, so nothing was run; retry after retryAfterSec seconds", errorCode: "fleet.lease_unavailable", reason: adm.cause, retryAfterSec: adm.retryAfterSec },
+                body: refusalBody({
+                    errorCode: "fleet.lease_unavailable",
+                    message: "quota lease unavailable — this deployment enforces budgets fail-closed and could not confirm this caller's budget with the quota center, so nothing was run; retry after retryAfterSec seconds",
+                    facts: { reason: adm.cause, retryAfterSec: adm.retryAfterSec },
+                }),
                 retryAfterSec: adm.retryAfterSec,
             };
         default: {
@@ -24,9 +52,16 @@ export function leaseRefusalOf(adm) {
 export function costQuotaRefusalOf(d) {
     return {
         status: 429,
-        body: { error: "cost quota exceeded", errorCode: "limit.cost_quota_exceeded", usedMicroUsd: d.usedMicroUsd, limitMicroUsd: d.limitMicroUsd, retryAfterSec: d.retryAfterSec, windowResetsAt: quotaWindowResetsAt(d) },
+        body: refusalBody({
+            errorCode: "limit.cost_quota_exceeded",
+            message: "cost quota exceeded",
+            facts: { usedMicroUsd: d.usedMicroUsd, limitMicroUsd: d.limitMicroUsd, retryAfterSec: d.retryAfterSec, windowResetsAt: quotaWindowResetsAt(d) },
+        }),
     };
 }
+function bodyTooLargeError(message, cap) {
+    return createCodedHttpError(413, "request.payload_too_large", message, limitFactsUnmeasured("body", "bytes", cap));
+}
 function sendLeaseRefusal(res, refusal) {
     const { error, errorCode, ...extra } = refusal.body;
     res.setHeader("retry-after", String(refusal.retryAfterSec));
@@ -46,7 +81,7 @@ export function createRequestGuards(ctx) {
         deps.metrics?.inc("cost_quota_rejected_total");
         const { status, body } = costQuotaRefusalOf(d);
         const { error, errorCode, ...extra } = body;
-        res.setHeader("retry-after", String(body.retryAfterSec));
+        res.setHeader("retry-after", String(d.retryAfterSec));
         sendError(res, status, errorCode, error, extra);
         return true;
     }
@@ -119,7 +154,7 @@ export function createRequestGuards(ctx) {
         deps.metrics?.inc("usage_window_rejected_total");
         deps.logger?.info?.("usage_window_exhausted", { hasPrincipal: key !== GLOBAL_USAGE_KEY, retryAfterMs });
         const retryAfterSec = Math.max(1, Math.ceil(retryAfterMs / 1000));
-        return { status: 429, body: { error: "usage window exhausted (deployment token governance)", errorCode: "usage.window_exhausted", retryAfterSec }, retryAfterSec };
+        return { status: 429, body: refusalBody({ errorCode: "usage.window_exhausted", message: "usage window exhausted (deployment token governance)", facts: { retryAfterSec } }), retryAfterSec };
     }
     async function usageWindowDenied(req, res) {
         const denial = await usageWindowDenialFor(gatedPrincipal(req, deps.config) || GLOBAL_USAGE_KEY);
@@ -151,7 +186,7 @@ export function createRequestGuards(ctx) {
     }
     function isFleetWide(req) {
         const tt = deps.config.traceToken;
-        return devOpenDeployment(deps.config) || systemFor(req, deps.config) !== undefined || (!!tt && authorized(req, tt));
+        return devOpenDeployment(deps) || systemFor(req, deps.config) !== undefined || (!!tt && authorized(req, tt));
     }
     function sessionOwnerScope(req) {
         const fleetWide = isFleetWide(req);
@@ -159,7 +194,7 @@ export function createRequestGuards(ctx) {
         return { fleetWide, gateOwner };
     }
     function sessionOwnerScopeForWrite(req) {
-        const fleetWide = devOpenDeployment(deps.config) || systemFor(req, deps.config) !== undefined;
+        const fleetWide = devOpenDeployment(deps) || systemFor(req, deps.config) !== undefined;
         const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null);
         return { fleetWide, gateOwner };
     }
@@ -176,10 +211,11 @@ export function createRequestGuards(ctx) {
         return true;
     }
     function runOwnerOk(req, res, owner) {
-        return ownerGate(req, res, (principal) => runOwnerReadable(principal, owner, deps.config), () => sendError(res, 404, "not_found.run", RUN_NOT_FOUND_MESSAGE));
+        return ownerGate(req, res, (principal) => runRowReadable(deps.config, principal, owner, "owner"), () => sendError(res, 404, "not_found.run", RUN_NOT_FOUND_MESSAGE));
     }
-    function sessionOwnerOk(req, res, owner) {
-        return ownerGate(req, res, (principal) => sessionOwnerReadable(principal, owner, deps.config), () => sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE));
+    function sessionOwnerOk(req, res, cell) {
+        const caller = sessionCallerOf(req, deps);
+        return ownerGate(req, res, () => sessionOwnerReadable(caller, cell, deps), () => sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE));
     }
     const sessionAssertAbsentWarned = new Set();
     function runSessionAcceptOk(req, res, run, face, notFoundError = RUN_NOT_FOUND_MESSAGE) {
@@ -195,7 +231,7 @@ export function createRequestGuards(ctx) {
         }
         if (asserted === run.sessionId)
             return true;
-        if (explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config.operatorPrincipals))
+        if (explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config))
             return true;
         sendError(res, 404, "not_found.run", notFoundError);
         return false;
@@ -206,7 +242,7 @@ export function createRequestGuards(ctx) {
         for await (const c of req) {
             size += c.length;
             if (size > MAX_BODY)
-                throw new HttpError(413, "request body too large");
+                throw bodyTooLargeError("request body too large", MAX_BODY);
             chunks.push(c);
         }
         if (chunks.length === 0)
@@ -215,7 +251,7 @@ export function createRequestGuards(ctx) {
             return JSON.parse(Buffer.concat(chunks).toString("utf8")) ?? {};
         }
         catch {
-            throw new HttpError(400, "invalid JSON body");
+            throw invalidJsonError("not_json");
         }
     }
     async function readRawBody(req, max) {
@@ -224,7 +260,7 @@ export function createRequestGuards(ctx) {
         for await (const c of req) {
             size += c.length;
             if (size > max)
-                throw new HttpError(413, "blob too large");
+                throw bodyTooLargeError("blob too large", max);
             chunks.push(c);
         }
         return Buffer.concat(chunks);

package/dist/http/resume-ctx-read.d.ts

@@ -23,6 +23,7 @@
  * 恰好没折码,把列错误漏了出来 = 巧合式正确)。两条车道现在同一份拒绝契约,本口只认它。
  */
 import type { CheckpointCtx } from "./route-ctx.js";
+import { type RefusalBody } from "./refusal-body.js";
 export type ResumeCtxRead = {
     readonly kind: "ok";
     readonly ctx: CheckpointCtx;
@@ -37,10 +38,6 @@ export declare function readResumeCtx(load: Promise<CheckpointCtx | null>): Prom
  *  文案只说「哪一行读不出来 + 该找谁」,不把店层 detail 拼上 wire(内部机件不上 wire,S-376 同律)。 */
 export declare function resumeCtxCorruptAnswer(where: string): {
     status: number;
-    body: {
-        error: string;
-        errorCode: string;
-        where: string;
-    };
+    body: RefusalBody;
 };
 //# sourceMappingURL=resume-ctx-read.d.ts.map

package/dist/http/resume-ctx-read.js

@@ -1,4 +1,5 @@
 import { SqlJsonColumnError, StoreCorruptError } from "../plugins/sql-json-column.js";
+import { refusalBody } from "./refusal-body.js";
 export async function readResumeCtx(load) {
     try {
         const ctx = await load;
@@ -15,11 +16,13 @@ export async function readResumeCtx(load) {
 export function resumeCtxCorruptAnswer(where) {
     return {
         status: 500,
-        body: {
-            error: "the stored resume context for this session cannot be read — nothing was decided and nothing was resumed. Ask whoever operates this deployment to look at the row named in `where`: it has to be repaired or removed before this session can resume.",
+        body: refusalBody({
             errorCode: "corrupt",
-            where,
-        },
+            message: "the stored resume context for this session cannot be read — nothing was decided and nothing was resumed. Ask whoever operates this deployment to look at the row named in `where`: it has to be repaired or removed before this session can resume.",
+            facts: {
+                where,
+            },
+        }),
     };
 }
 //# sourceMappingURL=resume-ctx-read.js.map

package/dist/http/resume-legs.d.ts

@@ -17,17 +17,41 @@ import type { DecideBinding } from "./wire-types.js";
 import type { CheckpointStoreFull } from "../plugins/store-backend.js";
 import type { HostDecision } from "../host-decision.js";
 import { type PlanApprovePermissionModeAfter } from "../task-settings.js";
-import type { RouteCtxBase, DriveResumeArgs, HostLegOutcome, PreparedPlanReview, ResumeLegOutcome } from "./route-ctx.js";
-import { type TrustedRunInternals } from "./durable-run-leg.js";
+import type { RouteCtxBase, DriveResumeArgs, HostLegOutcome, PreparedPlanReview, ResumeLegOutcome, WorkflowDecisionDelivery } from "./route-ctx.js";
 import type { RunRegistry, RouteHelpers, RouteLegs } from "./route-ctx.js";
 import type { createRequestGuards } from "./request-guards.js";
 import type { FlatServiceDeps } from "./server.js";
+import { type ResumeRefusalAnswer } from "./checkpoint-ctx.js";
 /**
  * 🔴 **一次 `CheckpointError` 拒的处置 —— 唯一读口**:{@link CHECKPOINT_ERROR_DISPOSITION} 的读法(doctrine 在那张表头)。resume 腿的 catch 臂只调它一次,
  * 行的落点与 wire 的 `retriable` 都读这一个结果。纯函数,钉直接调。运行期遇到表外的码(装树 core 比本二进制多一个码的版本偏斜 —— 型面上拼不出来)
  * ⇒ `"terminal"`:与 `by_reason` 认不得的词同一条 fail-closed 方向(不宽容默认成可重试),也与修前手列串的缺省逐字相同。
  */
 export declare function resumeRefusalDisposition(e: CheckpointError): "cancelled" | "retriable" | "terminal";
+/**
+ * 🔴 **引擎拒一次续跑(`CheckpointError`)的 HTTP 答复 —— 唯一组句器**(S-1690 / S-1692,core 7.52.0;五条续跑腿〔`/decide` · `/resume` · `/wake` · `plan_review` ·
+ * workflow 决定在宿主会话上起的新一跑〕同经 `driveResumeLeg` 的 catch 臂到这里,SLA 拒扫腿与 PARKED 赎回席经 `resumeCheckpoint` 同得)。
+ *
+ * 规则(一条):**一次拒 = 一个答复形,与「谁发现的」无关**。引擎在认领前 / CAS 前拒的,与本服务在重放存量体之前自己拒的(`resume_blocked_by_policy`,
+ * `checkpoint-ctx.ts` `resumeBlockedByPolicyAnswer`;续跑入口上卡仍 pending ⇒ 同样带 `retriable:true`)读同一组机读键;体经拒体组句器 `refusalBody` 铸,
+ * `retriable` 经续跑家族的唯一写点 `resumeRefusalWithCard` 追加。
+ * 一处如实例外:后台停驻子代的 parked 赎回不经本函数 —— 引擎的赎回回执只交成因词,`parked-decide.ts` 答 `422 parked_resume.startup_failed`,体只带 `cause`:
+ *  · `errorCode` —— 引擎码的原码镜像(`checkpoint.invalid_outcome` 按决断成因改铸,{@link decisionRefusalCauseOf});
+ *  · 引擎 `detail` 的三个机读判别位原样过境,键名与 `resume_blocked_by_policy` 同义:`detail.code` ⇒ `blockedBy`(挡住它的准入码 = 同一份坏配置在新跑上报的 `errorCode`;
+ *    今天只有 `checkpoint.config_refused` 带它)· `detail.field` ⇒ `field`(哪一侧 / 哪一格)· `detail.reason` ⇒ `reason`(同码多臂时哪一臂,闭集 `CheckpointErrorReason`)。
+ *    缺席不造键(引擎没给就是没给)。`detail` 的其余成员(`requires` / `differs`)不在这组判别位里,不上 wire;`retryAfterMs` 折成族口径的 `retryAfterSec`(下面);
+ *  · `retriable` —— 只在处置读口答 `retriable` 时在场(卡仍 pending、行重新 park;**不是**「原样重试会成功」—— 契约附录 A.1 注那一个意思,壳按它决定卡还挂不挂着)。
+ *    出路(改那一格再决 / 只能在停它的那一版 worker 上跑完或取消 / 等一会)由 `errorCode` + `field` + `blockedBy` + `reason` 与引擎的句子说;
+ *  · `error` —— 引擎的句子原样(它点名条目、哪一臂与出路);本层不另铸第二句;
+ *  · `taskId`(抢到行才在)/ `retryAfterSec`(两码闭集)/ 两版本键(只在 `checkpoint.unsupported_version`:调用方按那一码交 `buildCheckpointVersionKeys` 的产物,本函数原样铺)—— 键律照旧。
+ * 纯函数(钉直接调)。`retriable` 由调用方传入 —— 行的落点与 wire 的 `retriable` 读同一次求值(catch 臂一处),本函数不另判。
+ */
+export declare function checkpointRefusalAnswer(e: CheckpointError, at: {
+    readonly gate: string;
+    readonly retriable: boolean;
+    readonly taskId?: string;
+    readonly versionKeys: Readonly<Record<string, string>>;
+}): ResumeRefusalAnswer;
 export declare function createResumeLegs(ctx: {
     deps: FlatServiceDeps;
     runnerFor: FlatServiceDeps["runnerFor"];
@@ -56,8 +80,8 @@ export declare function createResumeLegs(ctx: {
         status: number;
         body: object;
     }>;
-    startFreshHostTurn: (sessionId: string, objective: string, principal: string | undefined, req: IncomingMessage, trustedInternals: TrustedRunInternals, runId: string) => Promise<HostLegOutcome>;
-    resumeWake: (sessionId: string, message: string | undefined, caller: string | undefined, req: IncomingMessage | undefined, acceptEarly?: boolean, workflowParkedResume?: DriveResumeArgs["workflowParkedResume"], ownerLeaseAdmittedFor?: string) => Promise<HostLegOutcome>;
+    startFreshHostTurn: (sessionId: string, objective: string, principal: string | undefined, req: IncomingMessage, workflowDecision: WorkflowDecisionDelivery, runId: string) => Promise<HostLegOutcome>;
+    resumeWake: (sessionId: string, message: string | undefined, caller: string | undefined, req: IncomingMessage | undefined, acceptEarly?: boolean, workflowDecision?: WorkflowDecisionDelivery, ownerLeaseAdmittedFor?: string) => Promise<HostLegOutcome>;
     preparePlanReview: (sessionId: string, log?: {
         taskId?: string;
         principalPresent?: boolean;