@sema-agent/server 7.132.0 → 7.134.0

package/dist/http/request-guards.js

@@ -1,8 +1,11 @@
 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 { gatedPrincipal, explicitOperatorOk, sessionOwnerReadable, sessionCallerOf, 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;
@@ -29,11 +32,15 @@ export function refuseSubmitBody(walls, body) {
 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: {
@@ -45,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));
@@ -67,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;
     }
@@ -140,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);
@@ -170,20 +184,6 @@ export function createRequestGuards(ctx) {
             return null;
         }
     }
-    function isFleetWide(req) {
-        const tt = deps.config.traceToken;
-        return devOpenDeployment(deps) || systemFor(req, deps.config) !== undefined || (!!tt && authorized(req, tt));
-    }
-    function sessionOwnerScope(req) {
-        const fleetWide = isFleetWide(req);
-        const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null);
-        return { fleetWide, gateOwner };
-    }
-    function sessionOwnerScopeForWrite(req) {
-        const fleetWide = devOpenDeployment(deps) || systemFor(req, deps.config) !== undefined;
-        const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null);
-        return { fleetWide, gateOwner };
-    }
     function ownerGate(req, res, readable, notFound) {
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && !principal) {
@@ -197,10 +197,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), () => 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) {
@@ -216,7 +217,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;
@@ -227,7 +228,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)
@@ -236,7 +237,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) {
@@ -245,11 +246,11 @@ 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);
     }
-    return { quotaExceeded, ownerCostQuotaDenied, ownerFleetLeaseDenied, ownerLeaseDenied, ownerQuotaDenied, leaseDenied, usageWindowDenialFor, usageWindowDenied, rateLimited, safeDecode, isFleetWide, sessionOwnerScope, sessionOwnerScopeForWrite, runOwnerOk, sessionOwnerOk, runSessionAcceptOk, readJson, readRawBody };
+    return { quotaExceeded, ownerCostQuotaDenied, ownerFleetLeaseDenied, ownerLeaseDenied, ownerQuotaDenied, leaseDenied, usageWindowDenialFor, usageWindowDenied, rateLimited, safeDecode, runOwnerOk, sessionOwnerOk, runSessionAcceptOk, readJson, readRawBody };
 }
 //# sourceMappingURL=request-guards.js.map

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

@@ -21,8 +21,21 @@
  * 早把列错误**折**成了一只普通 `Error` ⇒ 折后的错落进下面那条「店抖动 ⇒ 当缺席」臂,坏体与缺席在
  * 用户面上仍然同答 409 —— 正是 S-577 第二半要修的那个病,只是它当时只在 local 车道上修成了(那一侧
  * 恰好没折码,把列错误漏了出来 = 巧合式正确)。两条车道现在同一份拒绝契约,本口只认它。
+ *
+ * 🔴 **第四态 `unsealable`(S-1907,7.134.0):读出来了,但凭据位上的封签开不开**。店交出的是**落盘形**(凭据位上是封签,`StoredCheckpointCtx`);
+ * 本口在任何消费者看到之前经**唯一**开口 `openCheckpointCtx` 开封(规则属主 = `checkpoint-ctx.ts` 末段「凭据位密封」)—— 所以 `ok` 交出的恒是开封形,
+ * 没有哪条腿拿着封签去重建 spec。开不开(没有保管店 / 钥匙不在本副本 / 密文坏或不是本行封的 / 明文 / 认不出的封签)⇒ `unsealable`(`field` + `reason`),
+ * 各续跑入口答 {@link resumeCtxUnsealableAnswer}(409 `conflict.checkpoint_ctx_unsealable`)。**不折成缺席**(出路不同:缺席 = 重提;开不开 = 看 `reason`
+ * —— `key_not_held` 多半是多副本没共享保管目录,运维修好之后同一个决定原样重发即可),**不明文回落、不丢键**。
+ * 开封要知道这一行的会话(封签绑会话)与开口(`ServiceDeps.checkpointCtxSealing`;缺席 = 本副本没有保管店):两件一起交({@link CheckpointCtxOpening})。
+ *
+ * **两种读法,一只读口**(第二个实参):① 开封形({@link CheckpointCtxOpening})—— 续跑重建 spec 的每一条腿;② {@link KEEP_SEALED}「信封原样留着」——
+ * 只读**非凭据字段**的读者(今天 = inbox 的展示位 `objective`):不开封、不判凭据位(活凭据不为展示进内存),交回落盘形 `StoredCheckpointCtx`,
+ * 结局里没有 `unsealable` 这一态(型面就没有;店边界的三态与开封形逐字同一段)。凭据位上的值在这种读法里仍是封签 —— 谁要用它们就必须走读法 ①。
  */
 import type { CheckpointCtx } from "./route-ctx.js";
+import { type CheckpointCtxOpener, type CheckpointCtxUnsealableReason, type StoredCheckpointCtx } from "./checkpoint-ctx.js";
+import { type RefusalBody } from "./refusal-body.js";
 export type ResumeCtxRead = {
     readonly kind: "ok";
     readonly ctx: CheckpointCtx;
@@ -31,16 +44,47 @@ export type ResumeCtxRead = {
 } | {
     readonly kind: "corrupt";
     readonly where: string;
+} | {
+    readonly kind: "unsealable";
+    readonly field: string;
+    readonly reason: CheckpointCtxUnsealableReason;
+};
+/** 读法 ② 的结局:店边界的三态,`ok` 交落盘形(凭据位上仍是封签)。 */
+export type SealedResumeCtxRead = {
+    readonly kind: "ok";
+    readonly ctx: StoredCheckpointCtx;
+} | {
+    readonly kind: "absent";
+} | {
+    readonly kind: "corrupt";
+    readonly where: string;
+};
+/** 开封的两件:这一行的会话(= 交给店 `getCtx` 的那一个)与开口(缺席 = 本副本没有保管店)。 */
+export interface CheckpointCtxOpening {
+    readonly sessionId: string;
+    readonly opener: CheckpointCtxOpener | undefined;
+}
+/** 读法 ② 的词:信封原样留着(只读非凭据字段)。 */
+export declare const KEEP_SEALED = "keep_sealed";
+export declare function readResumeCtx(load: Promise<StoredCheckpointCtx | null>, opening: CheckpointCtxOpening): Promise<ResumeCtxRead>;
+export declare function readResumeCtx(load: Promise<StoredCheckpointCtx | null>, opening: typeof KEEP_SEALED): Promise<SealedResumeCtxRead>;
+/**
+ * 开不开的对外答复(S-1907)—— 409 `conflict.checkpoint_ctx_unsealable`,机读 `field`(哪一个凭据位,提交体路径;键名不是秘密,值从不进来)+ `reason`
+ * (闭集 `CHECKPOINT_CTX_UNSEALABLE_REASONS`)。句子说「这条任务的续跑上下文里带的凭据本服务开不开」、五种成因与出路(按 `reason` 修好保管目录后原样重发,
+ * 或作为新任务重提、仍停驻的先取消)。拒在任何状态改动之前:卡仍待决、行字节不动、`plan_review` 的一次性 nonce 未烧。
+ * 🔴 形是给冻结门看的(与 {@link resumeCtxCorruptAnswer} 同一条):`status: <三位数>, body: refusalBody({ errorCode: "<码>", message: "<整句双引号字面>"`,中间只许有空白。
+ */
+export declare function resumeCtxUnsealableAnswer(read: {
+    readonly field: string;
+    readonly reason: CheckpointCtxUnsealableReason;
+}): {
+    status: number;
+    body: RefusalBody;
 };
-export declare function readResumeCtx(load: Promise<CheckpointCtx | null>): Promise<ResumeCtxRead>;
 /** 坏体的对外答复 —— 与会话策略面**同码**(`session-policy-wire.ts` 的 `corrupt` ⇒ 500),不铸新词。
  *  文案只说「哪一行读不出来 + 该找谁」,不把店层 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,8 +1,18 @@
+import { openCheckpointCtx } from "./checkpoint-ctx.js";
 import { SqlJsonColumnError, StoreCorruptError } from "../plugins/sql-json-column.js";
-export async function readResumeCtx(load) {
+import { refusalBody } from "./refusal-body.js";
+export const KEEP_SEALED = "keep_sealed";
+export async function readResumeCtx(load, opening) {
+    const read = await readStoredCtx(load);
+    if (read.kind !== "ok" || opening === KEEP_SEALED)
+        return read;
+    const opened = openCheckpointCtx(read.ctx, opening.opener, opening.sessionId);
+    return opened.kind === "ok" ? { kind: "ok", ctx: opened.ctx } : { kind: "unsealable", field: opened.field, reason: opened.reason };
+}
+async function readStoredCtx(load) {
+    let stored;
     try {
-        const ctx = await load;
-        return ctx == null ? { kind: "absent" } : { kind: "ok", ctx };
+        stored = await load;
     }
     catch (e) {
         if (e instanceof StoreCorruptError)
@@ -11,15 +21,31 @@ export async function readResumeCtx(load) {
             throw e;
         return { kind: "absent" };
     }
+    return stored == null ? { kind: "absent" } : { kind: "ok", ctx: stored };
+}
+export function resumeCtxUnsealableAnswer(read) {
+    return {
+        status: 409,
+        body: refusalBody({
+            errorCode: "conflict.checkpoint_ctx_unsealable",
+            message: "this task's stored resume context holds credentials from its request (MCP / A2A headers or env values, settings.env, settings.webSearch.apiKey, or http hook headers) that this server cannot unseal — reason says why: no_key_store (this server has no sealed-key store), key_not_held (they were sealed with a key this server does not hold: another replica's, or a replaced sealed-key directory), unopenable (the sealed value is damaged or belongs to another session), plaintext (an older server version stored them unsealed), unrecognized_seal (a seal format this version does not know). Nothing was decided and nothing was resumed. If whoever operates this deployment restores the sealed-key directory that sealed them and restarts this server (it reads its keys only at startup), the same request can be sent again; otherwise submit the work again as a new task, and if this task is still suspended cancel it first (POST /v1/runs/:id/cancel).",
+            facts: {
+                field: read.field,
+                reason: read.reason,
+            },
+        }),
+    };
 }
 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,8 +17,7 @@ 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";
@@ -36,7 +35,8 @@ export declare function resumeRefusalDisposition(e: CheckpointError): "cancelled
  * 规则(一条):**一次拒 = 一个答复形,与「谁发现的」无关**。引擎在认领前 / 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`:
+ * 后台停驻子代的 parked 赎回不经本函数(引擎交的是赎回回执,不是 `CheckpointError`):`parked-decide.ts` 答 `422 parked_resume.startup_failed`,体带成因词 `cause`,
+ * 引擎 7.54.0 起回执的 `details.detail` 交出同三位判别位,经**同一只**读法 `resumeRefusalFacts` 落成同名三键(下面第二条)。键律:
  *  · `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`)。
@@ -81,8 +81,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;