@sema-agent/server 7.131.0 → 7.133.0

package/dist/http/approval-sweeps.js

@@ -1,15 +1,17 @@
 import { redactHead } from "../observability/run-terminal.js";
+const errText = (e) => redactHead(e instanceof Error ? e.message : String(e), 2000);
 import { findParkOrigin } from "../parked-decide.js";
 import { decodeCheckpointScope } from "../security.js";
 import { hostDecisionFacts } from "../host-decision.js";
 import { APPROVAL_GATE_KINDS } from "../tool-approval.js";
 import { createWallClockJumpGuard } from "../wall-clock-jump-guard.js";
-import { hasServiceAuth } from "./dispatch.js";
-import { gatedPrincipal } from "./principal-gate.js";
+import { gatedPrincipal, hasServiceAuth } from "./principal-gate.js";
 import { costQuotaRefusalOf } from "./request-guards.js";
 import { admissionRefusalOf, readinessOf } from "./readiness.js";
 import { readResumeCtx } from "./resume-ctx-read.js";
+import { isResumeBlockedByPolicy } from "./checkpoint-ctx.js";
 import { storedBodyReplayRefusal } from "./stored-body-replay.js";
+import { refusalBody } from "./refusal-body.js";
 const BLOCKED_SCALAR_KEYS = ["errorCode", "blockedBy", "field", "reason", "count", "cap", "index"];
 function blockedScalars(body) {
     const out = {};
@@ -22,8 +24,27 @@ function blockedScalars(body) {
     }
     return out;
 }
+const BLOCKED_WARNED_MAX = 1024;
 export function createApprovalSweeps(ctx) {
     const { deps, resumeCheckpoint, mayDiscloseRowError } = ctx;
+    const blockedWarned = new Map();
+    const noteResumeBlocked = (cardToken, sessionId, status, body) => {
+        deps.metrics?.inc("deny_sweep_resume_blocked_total");
+        const fields = { status, ...blockedScalars(body) };
+        if (cardToken !== undefined) {
+            const fingerprint = JSON.stringify(fields);
+            if (blockedWarned.get(cardToken) === fingerprint)
+                return;
+            blockedWarned.delete(cardToken);
+            if (blockedWarned.size >= BLOCKED_WARNED_MAX) {
+                const oldest = blockedWarned.keys().next();
+                if (oldest.done !== true)
+                    blockedWarned.delete(oldest.value);
+            }
+            blockedWarned.set(cardToken, fingerprint);
+        }
+        deps.logger?.warn?.("deny_sweep_resume_blocked", { sessionId, ...fields });
+    };
     const denySweepClockGuard = createWallClockJumpGuard({
         slaMs: deps.config.approvalTimeoutSec > 0 ? deps.config.approvalTimeoutSec * 1000 : undefined,
         onJump: ({ jumpMs, graceMs }) => deps.logger?.warn?.("deny_sweep_wall_clock_jump", {
@@ -45,26 +66,41 @@ export function createApprovalSweeps(ctx) {
             return;
         if (!denySweepClockGuard.admit(now))
             return;
-        const expired = await cs.listExpiredApprovalGates(now).catch(() => []);
-        const isParkedOwned = async (sessionId) => {
-            if (deps.backgroundAgentStore === undefined && deps.workflowAgentSessionIndex === undefined)
-                return false;
+        let expired;
+        try {
+            expired = await cs.listExpiredApprovalGates(now);
+        }
+        catch (e) {
+            deps.metrics?.inc("deny_sweep_list_failed_total");
+            deps.logger?.warn?.("deny_sweep_list_failed", {
+                err: errText(e),
+                note: "the SLA deny-sweep could not read the expired approvals this tick, so nothing was denied and nothing was skipped; the rows stay suspended and are read again next tick (the terminal backstop still reaps them)",
+            });
+            return;
+        }
+        const parkSources = deps.backgroundAgentStore !== undefined || deps.workflowAgentSessionIndex !== undefined;
+        const cardOf = async (sessionId) => {
+            let token;
             try {
-                const token = await cs.findPendingTokenBySession(sessionId, undefined, { gateKinds: APPROVAL_GATE_KINDS });
+                token = (await cs.findPendingTokenBySession(sessionId, undefined, { gateKinds: APPROVAL_GATE_KINDS })) ?? undefined;
                 if (!token)
-                    return false;
+                    return { token, parked: false, rev: undefined };
                 const cp = await cs.get(token);
                 if (!cp)
-                    return false;
-                return (await findParkOrigin({
+                    return { token, parked: false, rev: undefined };
+                const rev = cp.rev ?? 0;
+                if (!parkSources)
+                    return { token, parked: false, rev };
+                const origin = await findParkOrigin({
                     ...(deps.backgroundAgentStore !== undefined ? { agentStore: deps.backgroundAgentStore } : {}),
                     ...(deps.workflowAgentSessionIndex !== undefined && deps.workflowRunStore !== undefined
                         ? { workflowIndex: deps.workflowAgentSessionIndex, workflowRunStore: deps.workflowRunStore }
                         : {}),
-                }, { token, scope: cp.scope, sessionId: cp.sessionId })) !== undefined;
+                }, { token, scope: cp.scope, sessionId: cp.sessionId });
+                return { token, parked: origin !== undefined, rev };
             }
             catch {
-                return false;
+                return { token, parked: false, rev: undefined };
             }
         };
         const storedBodyUnservable = async (sessionId) => {
@@ -75,10 +111,35 @@ export function createApprovalSweeps(ctx) {
                 return undefined;
             return storedBodyReplayRefusal(read.ctx, deps.config);
         };
+        const expirePolicyBlockedCard = async (cardToken, observedRev, sessionId, body) => {
+            let won;
+            try {
+                const cp = await cs.get(cardToken);
+                if (!cp)
+                    return;
+                if (cp.status !== "pending" || (cp.rev ?? 0) !== observedRev) {
+                    deps.logger?.warn?.("deny_sweep_policy_blocked_expire_skipped", { sessionId, skipReason: cp.status !== "pending" ? "not_pending" : "card_changed", ...blockedScalars(body) });
+                    return;
+                }
+                won = await cs.expire(cardToken, cp.scope);
+            }
+            catch (e) {
+                deps.logger?.warn?.("deny_sweep_policy_blocked_expire_failed", { sessionId, err: errText(e) });
+                return;
+            }
+            blockedWarned.delete(cardToken);
+            if (won)
+                deps.metrics?.inc("deny_sweep_policy_blocked_expired_total");
+            deps.logger?.warn?.("deny_sweep_policy_blocked_expired", { sessionId, won, ...blockedScalars(body) });
+        };
         let parkedSkipped = 0;
         const replaySkipped = [];
+        const seenCards = new Set();
         for (const { sessionId } of expired) {
-            if (await isParkedOwned(sessionId)) {
+            const { token: cardToken, parked, rev: cardRev } = await cardOf(sessionId);
+            if (cardToken !== undefined)
+                seenCards.add(cardToken);
+            if (parked) {
                 parkedSkipped += 1;
                 continue;
             }
@@ -87,9 +148,26 @@ export function createApprovalSweeps(ctx) {
                 replaySkipped.push({ sessionId, kind: unservable.kind });
                 continue;
             }
-            await resumeCheckpoint(sessionId, "deny", "approval SLA expired — auto-denied", { decidedBy: "sla_timeout" }).then((r) => { if (r.status >= 400)
-                deps.logger?.warn?.("deny_sweep_resume_blocked", { sessionId, status: r.status, ...blockedScalars(r.body) }); }, (e) => deps.logger?.warn?.("deny_sweep_resume_failed", { sessionId, err: redactHead(e instanceof Error ? e.message : String(e), 2000) }));
+            let out;
+            try {
+                out = await resumeCheckpoint(sessionId, "deny", "approval SLA expired — auto-denied", { decidedBy: "sla_timeout" });
+            }
+            catch (e) {
+                deps.logger?.warn?.("deny_sweep_resume_failed", { sessionId, err: errText(e) });
+                continue;
+            }
+            if (out.status < 400) {
+                if (cardToken !== undefined)
+                    blockedWarned.delete(cardToken);
+                continue;
+            }
+            noteResumeBlocked(cardToken, sessionId, out.status, out.body);
+            if (isResumeBlockedByPolicy(out) && cardToken !== undefined && cardRev !== undefined)
+                await expirePolicyBlockedCard(cardToken, cardRev, sessionId, out.body);
         }
+        for (const token of [...blockedWarned.keys()])
+            if (!seenCards.has(token))
+                blockedWarned.delete(token);
         if (parkedSkipped > 0)
             deps.logger?.info?.("deny_sweep_parked_skipped", { count: parkedSkipped });
         if (replaySkipped.length > 0) {
@@ -103,10 +181,10 @@ export function createApprovalSweeps(ctx) {
     async function redeemParkedAsk(req) {
         const cs = deps.checkpointStore;
         if (!cs) {
-            return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+            return { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
         }
         if (!hasServiceAuth(deps.config) && !deps.config.allowUnauthedWrites) {
-            return { status: 503, body: { error: "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting task submissions", errorCode: "auth.service_token_required" } };
+            return { status: 503, body: refusalBody({ errorCode: "auth.service_token_required", message: "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting task submissions" }) };
         }
         const refusal = admissionRefusalOf(readinessOf(deps), deps.servingLease?.(), "hitl-answer");
         if (refusal !== undefined)
@@ -128,17 +206,17 @@ export function createApprovalSweeps(ctx) {
         catch (e) {
             if (!(await mayDiscloseRowError(cs, req.gateToken, { principal: req.principal, explicitOperator: false }))) {
                 deps.logger?.warn?.("parked_late_decision_unreadable_row_withheld", { askId: req.askId });
-                return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+                return { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
             }
-            return { status: 409, body: { error: e instanceof Error ? e.message : String(e), errorCode: "conflict.checkpoint_unreadable" } };
+            return { status: 409, body: refusalBody({ errorCode: "conflict.checkpoint_unreadable", message: e instanceof Error ? e.message : String(e) }) };
         }
         if (!cp) {
-            return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+            return { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
         }
         const cpPrincipal = decodeCheckpointScope(cp.scope);
         if (cpPrincipal !== undefined && cpPrincipal !== req.principal) {
             deps.logger?.warn?.("parked_late_decision_scope_mismatch", { askId: req.askId });
-            return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+            return { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
         }
         const binding = {
             checkpointToken: req.gateToken,

package/dist/http/caller-trust.d.ts

@@ -0,0 +1,77 @@
+/**
+ * **调用方信任档** —— 一份请求里「不经人答就生效」的规则表按谁的档准入:全仓唯一一张表({@link callerTrust})、唯一一只准入判({@link requestTrustRefusal})。
+ *
+ * ## 律
+ * 契约(settings-schema `SAFETY_MERGE_SPEC.permissions` 的成员阶梯)按**层的信任档**准入每个成员:`allow` 放宽免问面(`loosen`),要 `global`;`deny` / `ask` 只收紧,
+ * 文件层最低档 `local` 就收。wire 上没有层 —— 提交体是合并后的扁平结果,层只在合并端(cli 本地)存在;自报一个层 / 作者位不可验(引擎侧已拒立这种位)。所以本服务
+ * 的「层」= **这次请求验过的凭据**:档只由部署形 + 身份来源 + 登录令牌的 scope 角色推,调用方说什么都不改档。
+ *
+ *  · 单用户 turnkey(`requirePrincipal !== true`,本仓 posture 判别式同一只)⇒ `global`:一台机一位超管;
+ *  · 多租 · 部署的 service 凭据 ⇒ `global`:部署自己的凭据是运维档(契约给「启动方自己的行为」—— `SETTINGS_SOURCE_CONTRACT.flagSettings` —— 的档),持它的前端为自己转发的内容负责;
+ *    出示的 Bearer 就是 service 凭据时,哪怕它同时也被鉴权桥验成登录令牌,也按 service 凭据读(与凭据门派 `source` 同序:`dispatch.ts` 先认 service 凭据);
+ *  · 多租 · 中心登录令牌,scope 角色 ≥ 契约 `domainWriteRole("governance")` ⇒ `global`:能写 scope 治理域(autonomy / commandPolicy / approvalRequire,全组织的免问面)
+ *    的角色,放宽自己这一 run 是它的子集;门槛读契约,不手抄角色词;
+ *  · 多租 · 其余(登录令牌角色低于它 / 不带 / 认不出;直连门 principal 令牌只证身份不证角色;没有验过的凭据)⇒ `project`:契约给非运维档作者的仓控来源的档,
+ *    收紧成员照收、放宽成员不收 —— 没有可验的角色就落到这里(fail-closed)。
+ *
+ * **判的是哪些表**:请求体上不经人答就生效的规则表 —— `settings.permissions` 的每个成员桶(逐 `membersOf("permissions")`),以及请求**按名点用**(`userInvokedSkills`)的
+ * 自带技能的两只清单(引擎 `seedSkillGrants`:人点的名就是表态,不出 `Skill` 卡 ⇒ `allowedTools` 是 `allow` 成员的孪生、`disallowedTools` 是 `deny` 的孪生,键 → 成员一张表
+ * {@link SKILL_LIST_MEMBER})。没点用的自带技能不判:它的清单要经 `Skill` 卡上的人点头才生效 —— 那正是契约给低于门槛的放宽指定的同意出口。
+ * 准入只经契约导出:桶非空且 `!isAtLeast(档, memberAdmission(…).minTrust)` ⇒ 不准入;不按方向开特例(契约的层准入同样先判 floor)。
+ * 不准入 ⇒ 受理口 400,体与条目问题同形(`entry-problems.ts`:`field` + `detail.problems` + `total`),原因词 = 契约 `LAYER_ADMISSION_VERDICTS` 的 `below_trust_floor`,
+ * 另带 `detail.callerTrust`(这次请求的档)。响亮拒而不是静默丢:契约要求低于门槛的放宽不得静默吞,出路是同意(答卡)或运维的 allow 表。
+ *
+ * 读者(都读同一次求值,不各算一份):提交受理口(`admission.ts` `prepareSpec`,三提交面共用)与能力位 `settings.permissions.callerTrust`(`routes/capabilities.ts`)。
+ * 续跑腿不读本档:存储体在自己的受理口按当时的档准入过。
+ */
+import type { IncomingMessage } from "node:http";
+import { type MinTrust, type SafetyMergeMember, type UserRole } from "@sema-agent/settings-schema";
+import type { SkillSpec } from "@sema-agent/core";
+import type { ServiceConfig } from "../config-types.js";
+import { type EntryProblem } from "../entry-problems.js";
+import type { ParsedTaskSettings } from "../task-settings.js";
+/**
+ * 档是**怎么**推出来的(闭集;拒句按它说出路)。加一个词 ⇒ {@link basisClause} 的穷举 switch 编译红。
+ *  · `single_user` —— 单用户 turnkey;
+ *  · `service_credential` —— 多租 · 部署的 service 凭据;
+ *  · `sign_in_role` —— 多租 · 登录令牌带契约阶梯里的角色(够不够档看 `trust`);
+ *  · `sign_in_role_unrecognized` —— 多租 · 登录令牌不带角色,或角色不在契约阶梯里;
+ *  · `identity_without_role` —— 多租 · 直连门 principal 令牌(只证身份);
+ *  · `unverified` —— 多租 · 没有验过的凭据。
+ */
+export type CallerTrustBasis = "single_user" | "service_credential" | "sign_in_role" | "sign_in_role_unrecognized" | "identity_without_role" | "unverified";
+/** 一次求值的读数。`role` 只在 `basis === "sign_in_role"` 时在场(契约阶梯里的词)。 */
+export interface CallerTrust {
+    readonly trust: MinTrust;
+    readonly basis: CallerTrustBasis;
+    readonly role?: UserRole;
+}
+/** 档表(唯一一张)。规则全文见文件头。 */
+export declare function callerTrust(req: IncomingMessage, config: ServiceConfig): CallerTrust;
+/** 请求 `settings.permissions` 的成员桶 —— 按**契约的成员型**取:契约加成员而本仓的请求桶没有它 ⇒ 这里编译红(本仓必须先决定那只桶怎么上 wire)。 */
+type RequestPermissionMembers = Pick<NonNullable<ParsedTaskSettings["permissions"]>, SafetyMergeMember<"permissions">>;
+/** 准入判的输入:解析后的请求桶(`parseTaskSettings` 的读数 = `applyTaskSettings` 投进引擎的那一份)+ 请求自带技能 + 按名点用的技能名(两者受理门已判过形)。 */
+export interface RequestRuleTables {
+    readonly permissions: RequestPermissionMembers | undefined;
+    readonly skills: readonly Pick<SkillSpec, "name" | "allowedTools" | "disallowedTools">[] | undefined;
+    readonly userInvokedSkills: readonly string[] | undefined;
+}
+/** 受理口拒体:句子 + 机读位(原样进 `sendError` 的 facts)。 */
+export interface RequestTrustRefusal {
+    readonly message: string;
+    readonly facts: {
+        readonly field: string;
+        readonly detail: {
+            readonly problems: readonly EntryProblem[];
+            readonly total: number;
+            readonly callerTrust: MinTrust;
+        };
+    };
+}
+/**
+ * 请求里不经人答就生效的规则表的成员级准入(唯一一只判)。全部准入 ⇒ `undefined`;否则句子说扫描序里**第一张**不准入的表(坐标、档、floor、出路),
+ * 机读位把这一遍判下来的**全部**条目一次列全。空表什么也不改,不算。
+ */
+export declare function requestTrustRefusal(tables: RequestRuleTables, reading: CallerTrust): RequestTrustRefusal | undefined;
+export {};
+//# sourceMappingURL=caller-trust.d.ts.map

package/dist/http/caller-trust.js

@@ -0,0 +1,143 @@
+import { domainWriteRole, isAtLeast, isRole, memberAdmission, membersOf, roleAtLeast, USER_ROLES, } from "@sema-agent/settings-schema";
+import { entryProblem, entryProblemsFacts } from "../entry-problems.js";
+import { ssoVerifiedRole } from "../security.js";
+import { systemFor, verifiedIdentitySource } from "./principal-gate.js";
+export function callerTrust(req, config) {
+    if (config.requirePrincipal !== true)
+        return { trust: "global", basis: "single_user" };
+    const source = verifiedIdentitySource(req, config);
+    switch (source) {
+        case "service_token":
+            return { trust: "global", basis: "service_credential" };
+        case "sso": {
+            if (systemFor(req, config) !== undefined)
+                return { trust: "global", basis: "service_credential" };
+            const role = ssoVerifiedRole(req);
+            if (role === undefined || !isRole(role))
+                return { trust: "project", basis: "sign_in_role_unrecognized" };
+            return { trust: roleAtLeast(role, domainWriteRole("governance")) ? "global" : "project", basis: "sign_in_role", role };
+        }
+        case "direct_door_jwt":
+            return { trust: "project", basis: "identity_without_role" };
+        case undefined:
+            return { trust: "project", basis: "unverified" };
+        default: {
+            const unknownSource = source;
+            throw new Error(`callerTrust: identity source ${String(unknownSource)} has no trust row`);
+        }
+    }
+}
+const TRUST_REFUSAL_CODE = "request.field_invalid";
+const BELOW_TRUST_FLOOR = "below_trust_floor";
+const SKILL_LIST_MEMBER = { allowedTools: "allow", disallowedTools: "deny" };
+function effectiveRuleTables(t) {
+    const out = [];
+    if (t.permissions !== undefined) {
+        for (const member of membersOf("permissions")) {
+            const entries = t.permissions[member];
+            if (entries !== undefined)
+                out.push({ member, field: `settings.permissions.${member}`, entries, source: "settings" });
+        }
+    }
+    if (t.skills !== undefined && t.userInvokedSkills !== undefined) {
+        const named = new Set();
+        for (const name of t.userInvokedSkills) {
+            if (named.has(name))
+                continue;
+            named.add(name);
+            const at = t.skills.findIndex((skill) => skill.name === name);
+            const skill = t.skills[at];
+            if (skill === undefined)
+                continue;
+            for (const key of ["allowedTools", "disallowedTools"]) {
+                const entries = skill[key];
+                if (entries !== undefined)
+                    out.push({ member: SKILL_LIST_MEMBER[key], field: `skills[${at}].${key}`, entries, source: "invoked_skill" });
+            }
+        }
+    }
+    return out;
+}
+export function requestTrustRefusal(tables, reading) {
+    const problems = [];
+    let first;
+    for (const table of effectiveRuleTables(tables)) {
+        if (table.entries.length === 0)
+            continue;
+        const admission = memberAdmission("permissions", table.member);
+        if (isAtLeast(reading.trust, admission.minTrust))
+            continue;
+        first ??= { table, minTrust: admission.minTrust, loosens: directionLoosens(admission.direction) };
+        for (const entry of table.entries)
+            problems.push(entryProblem(TRUST_REFUSAL_CODE, table.field, entry, BELOW_TRUST_FLOOR));
+    }
+    if (first === undefined)
+        return undefined;
+    const facts = entryProblemsFacts(problems);
+    return {
+        message: `${first.table.field} needs trust "${first.minTrust}" (${whatItDoes(first.table.source, first.loosens)}) and this request is admitted at "${reading.trust}": ${basisClause(reading)}. Below that trust these rules are not applied — ${outletOf(first.table.source, first.loosens)}.`,
+        facts: { field: facts.field, detail: { ...facts.detail, callerTrust: reading.trust } },
+    };
+}
+function whatItDoes(source, loosens) {
+    const effect = loosens ? "lets matching calls run without a person being asked" : "changes which calls are asked or refused";
+    switch (source) {
+        case "settings":
+            return `it ${effect}`;
+        case "invoked_skill":
+            return `the request invokes this skill by name, so the list applies with no approval card and ${effect}`;
+        default: {
+            const unknownSource = source;
+            throw new Error(`requestTrustRefusal: rule table source ${String(unknownSource)} unknown`);
+        }
+    }
+}
+function outletOf(source, loosens) {
+    if (!loosens)
+        return "remove them, or ask the operator to set them deployment-wide";
+    switch (source) {
+        case "settings":
+            return "remove them and answer the approval questions as they come, or ask the operator to put them in APPROVAL_GRANT";
+        case "invoked_skill":
+            return "drop the skill from userInvokedSkills (the model can still activate it behind its approval card), remove the list, or ask the operator to put the rules in APPROVAL_GRANT";
+        default: {
+            const unknownSource = source;
+            throw new Error(`requestTrustRefusal: rule table source ${String(unknownSource)} unknown`);
+        }
+    }
+}
+function directionLoosens(direction) {
+    switch (direction) {
+        case "loosen":
+            return true;
+        case "tighten":
+            return false;
+        default: {
+            const unknownDirection = direction;
+            throw new Error(`requestTrustRefusal: member direction ${String(unknownDirection)} unknown`);
+        }
+    }
+}
+function basisClause(reading) {
+    const governanceRole = domainWriteRole("governance");
+    const reach = `the deployment's service credential, or a registry sign-in token whose role in its active scope is "${governanceRole}" or higher (the role that may write the scope's governance), is admitted at "global"`;
+    switch (reading.basis) {
+        case "single_user":
+            return `this single-user deployment admits every caller at "global"`;
+        case "service_credential":
+            return `the deployment's service credential is admitted at "global"`;
+        case "sign_in_role":
+            return `the registry sign-in token's role in its active scope is "${reading.role ?? ""}" — ${reach}; a scope admin can raise the role`;
+        case "sign_in_role_unrecognized":
+            return `the registry sign-in token carries no role this deployment recognizes (${USER_ROLES.join(" < ")}) — ${reach}`;
+        case "identity_without_role":
+            return `a direct-door principal token proves who the caller is, not a role — ${reach}`;
+        case "unverified":
+            return `the request carries no credential this deployment verifies — ${reach}`;
+        default: {
+            const unknownBasis = reading.basis;
+            throw new Error(`requestTrustRefusal: trust basis ${String(unknownBasis)} unknown`);
+        }
+    }
+}
+//# sourceMappingURL=caller-trust.js.map

package/dist/http/checkpoint-ctx.d.ts

@@ -48,6 +48,7 @@ import type { PermissionMode } from "@sema-agent/core";
 import type { CheckpointCtx } from "./route-ctx.js";
 import type { TaskRequestBody } from "./wire-types.js";
 import type { InertToolListEntry } from "../rule-entry-list.js";
+import { type Refusal } from "./refusal-body.js";
 /** 读法记号的闭集(一词 = 当前读法):这一行体里的 `settings.permissions.allow` 是按「交给引擎的 allow 层」写下、也该按它读的
  *  (与能力位 `settings.permissions.allowLayer` 同一个说法)。 */
 export declare const PERMISSIONS_ALLOW_READINGS: readonly ["allow_layer"];
@@ -98,18 +99,11 @@ export declare function withPermissionModeRewritten(ctx: CheckpointCtx, body: Ta
  *  记号缺席或认不得 ⇒ 不是「按当前读法写下」的证据,与 allow 记号同一条纪律。 */
 export declare function permissionModeReadingStated(ctx: CheckpointCtx): boolean;
 /**
- * 第三问的拒答复 —— 码与落点同 allow 记号那一问(`checkpoint.unsupported_version`,409,`retriable:true` = 那张卡仍 pending,**不是**「原样重试会成功」)。
+ * 第三问的拒答复 —— 码与落点同 allow 记号那一问(`checkpoint.unsupported_version`,409;卡仍 pending 时体上的 `retriable:true` 由 {@link resumeRefusalWithCard} 追加,本铸点不带)。
  * 句子说原因(更早的版本在每次续跑重钳运维的 AUTONOMY、没把它记进任务;本版只在提交时记一次 ⇒ 续跑会按任务提交时的原词跑)与两条出路。
- * 🔴 形是给冻结门看的:`status: <三位数>, body: { error: "<整句双引号字面>", errorCode: "<码>"`,中间只许有空白。
+ * 🔴 形是给冻结门看的:`status: <三位数>, body: refusalBody({ errorCode: "<码>", message: "<整句双引号字面>"`,中间只许有空白。
  */
-export declare function permissionModeReadingRefusal(): {
-    status: number;
-    body: {
-        error: string;
-        errorCode: string;
-        retriable: true;
-    };
-};
+export declare function permissionModeReadingRefusal(): ResumeRefusalAnswer;
 /**
  * 本行能否被按当前读法重放:体里 `allow` 在生效而行上的记号不是当前这一个词 ⇒ **不能**(`true` = 拒)。
  * 记号缺席、是旧词(`"statement"`)或认不得(手改 / 将来的写者)⇒ 同样拒:只有当前这个词是「按当前读法写下」的证据。
@@ -118,20 +112,13 @@ export declare function allowListReadingUnstated(ctx: CheckpointCtx): boolean;
 /** 被拒的行是哪一代写的(只在 {@link allowListReadingUnstated} 为真时有意义):记号是 `"statement"` ⇒ 表态时代;其余(缺席 / 认不得)⇒ 名单时代。 */
 export declare function allowListReadingEraOf(ctx: CheckpointCtx): AllowListReadingEra;
 /**
- * 拒的答复 —— 码与落点照「退役 mode-seed 行」的先例(`checkpoint.unsupported_version`,409,`retriable:true` = 那张卡仍 pending;**不是**「原样重试会成功」)。
+ * 拒的答复 —— 码与落点照「退役 mode-seed 行」的先例(`checkpoint.unsupported_version`,409;卡仍 pending 时的 `retriable:true` 由 {@link resumeRefusalWithCard} 追加,本铸点不带)。
  * 拒在认领之前,所以没有 `taskId`(行没抢到就不造键)。句子按这一行是哪一代写的分两句(闭集穷举,加一代 ⇒ 编译红):说原因(这条任务停在哪种读法上、
  * 照当前读法续跑会放宽什么)与出路(作为新任务重提,仍停驻的先取消)。
  *
- * 🔴 形是给冻结门看的(`api-error-text-freeze` 的 resume 家族收集器):`status: <三位数>, body: { error: "<整句双引号字面>", errorCode: "<码>"`,中间只许有空白。
+ * 🔴 形是给冻结门看的(`api-error-text-freeze` 的 resume 家族收集器):`status: <三位数>, body: refusalBody({ errorCode: "<码>", message: "<整句双引号字面>"`,中间只许有空白。
  */
-export declare function allowListReadingRefusal(era: AllowListReadingEra): {
-    status: number;
-    body: {
-        error: string;
-        errorCode: string;
-        retriable: true;
-    };
-};
+export declare function allowListReadingRefusal(era: AllowListReadingEra): ResumeRefusalAnswer;
 /**
  * 一条停驻行的持久化体在本版上**不能**重放时,是哪一条规则拒的(闭集;加一条 ⇒ {@link storedBodyReplayAnswer} 的 switch 编译红)。
  * 答 `checkpoint.unsupported_version` 的两臂随带这一行的写者版本(续跑上下文的 `writerVersion`,缺席 = 本版之前写下的行)—— 那一码的两版本键由它铸({@link buildCheckpointVersionKeys})。
@@ -168,11 +155,36 @@ export interface ResumeRefusalAnswer {
     } & Record<string, unknown>;
 }
 /**
- * 「续跑被一条准入策略挡住」的**唯一**铸点:`resolveSpec` 在重放存量体时抛出的 `HttpError`(400 族)折成 409 `resume_blocked_by_policy`,
- * `blockedBy` = 那条 400 的码(属主 `http/send.ts` `httpErrorCode`),`extra` 原样随体。{@link storedBodyReplayAnswer} 的工具名清单那一臂与
+ * 「续跑被一条准入策略挡住」的**唯一**铸点:`resolveSpec` 在重放存量体时抛出的 `HttpError`(400 族)折成 409 `resume_blocked_by_policy`。
+ * 入参是内层那只拒的 {@link Refusal}(`HttpError` 经 `http/send.ts` 的 `httpErrorRefusal` 读 —— 拆 `HttpError` 的唯一一处,码的属主 `httpErrorCode`):
+ * `blockedBy` = 内层的码,句子 = 前缀 + 内层的句子,内层的机读事实原样随体。{@link storedBodyReplayAnswer} 的工具名清单那一臂与
  * `resume-legs.ts` 的折叠口都调它 —— 句子与码只在这里写一次(冻结门 `api-error-text-freeze` 的模板骨架表锚这一处)。
+ *
+ * 🔴 **句尾点名出口**:这一拒不消费卡(卡仍 pending、run 行留停驻),被挡在一张 deny 不掉的卡前面的调用方需要知道怎么收场 ——
+ * `POST /v1/runs/:id/cancel` 对停驻的 run 直接结算(CAS 过期该卡再终局 run 行,不跑模型轮)。句子写「若仍停驻」而不是随卡有无换话:有卡 / 无卡(终态 run 的 steer 在铸唤醒卡之前拒)
+ * 两种处境除 `retriable` 外逐字同体(同判同答),与另两类存量体拒(allow 读法 / 模式词读法)句子里的出口是同一个端点、同一种写法。
+ *
+ * 本铸点**不带** `retriable`:那是调用点的事实(有没有一张待批卡仍在等),由 {@link resumeRefusalWithCard} 一处追加 —— 续跑入口(卡仍 pending、run 行留 `suspended`)
+ * 带 `retriable:true`,终态 run 的 steer 在铸唤醒卡之前拒(没有卡)不带。键集 = `errorCode` · `error` · `blockedBy` · (`field` · `reason` · 其余 `extra`,有才在)
+ * · (`retriable`,卡在才在)。
+ */
+export declare function resumeBlockedByPolicyAnswer(inner: Refusal): ResumeRefusalAnswer;
+/**
+ * 一次续跑的答复是不是 {@link resumeBlockedByPolicyAnswer} 铸的那一只(409 `resume_blocked_by_policy`)—— SLA 拒扫腿据此区分「同一份字节在本版永远被拒」与别的 ≥400
+ * (后者可能是瞬时的,照旧逐拍重试)。码的写端与读端住在同一个模块,读端不在别处第二次手拼这个字面。
  */
-export declare function resumeBlockedByPolicyAnswer(message: string, blockedBy: string, extra?: Record<string, unknown> | undefined): ResumeRefusalAnswer;
+export declare function isResumeBlockedByPolicy(answer: {
+    readonly status: number;
+    readonly body: unknown;
+}): boolean;
+/**
+ * 🔴 **三类续跑拒体上 `retriable` 的唯一写点**(本服务重放存量体前的拒、准入策略折叠、引擎拒的续跑):卡仍 pending(`cardPending`)⇒ 体尾追加 `retriable: true`;
+ * 否则体原样(键缺席)。这三类拒上规则一条:`retriable` 在场 ⇔ 有一张待批卡仍在等、run 行留 `suspended`(**不是**「原样重试会成功」—— 契约附录 A.1 注那一个意思)。
+ * 门型对不上的早拒(`gate_not_resumable` 一族)不经这里、不带它。三个调用点各交自己的事实:
+ * {@link storedBodyReplayAnswer}(调用方的 `cardPending`)、`resume-legs.ts` 的准入策略折叠口(续跑入口,恒有卡)与 `checkpointRefusalAnswer`(引擎拒的处置读口答 `retriable`)。
+ * 排在体尾:拒绝带来的附带键不得抹掉它。纯函数。
+ */
+export declare function resumeRefusalWithCard(answer: ResumeRefusalAnswer, cardPending: boolean): ResumeRefusalAnswer;
 /**
  * `stored-body-replay.ts` `storedBodyReplayRefusal` 的**日志字段**(三处问点同一形,各自只再加坐标键 `sessionId` / `taskId`):`kind` 判别,allow 臂带 `era`、技能臂带 `layer`,`note` 一句出路。
  * 事件名三个(问点各一:`resume_refused_stored_body` / `steer_wake_park_refused_stored_body` / `deny_sweep_stored_body_skipped`),字段形只有这一只。
@@ -189,6 +201,11 @@ export declare function storedBodyReplayLogFields(refusal: StoredBodyReplayRefus
  * `stored-body-replay.ts` `storedBodyReplayRefusal` 的答复:每条规则一只既有铸点(allow 记号 ⇒ {@link allowListReadingRefusal};模式词记号 ⇒ {@link permissionModeReadingRefusal};
  * 这两只答 `checkpoint.unsupported_version`,体按那一码的键律补两版本键,`readerVersion` = 调用方传的本进程服务版本;工具名清单 ⇒ {@link resumeBlockedByPolicyAnswer},与提交腿的 400
  * (该层的拒码:`request.field_invalid` / `config.agent.unknown_tool` / `config.tool_face_control`)同码同句 —— 体上只有这一个问题时;存量体同时还踩中 `resolveSpec` 更早的拒〔三桶超帽 / 托管姿态〕时,提交侧答更早那条、续跑侧答本句,两边都是拒,指路不同)。
+ *
+ * 🔴 `cardPending` —— **调用方交出的事实**:这一次拒的时候,有没有一张待批卡仍在等。`retriable:true` 说的恰是「卡仍 pending」,所以它只在卡在时在场(经
+ * {@link resumeRefusalWithCard} 一处写):续跑入口(`/decide` · `/resume` · `/wake` · plan_review · workflow 决定的新一跑,五个问点里除下面这一个之外全部)传 `true`;
+ * 终态 run 的 `POST /v1/runs/:id/steer` 在**铸唤醒卡之前**就拒,没有卡也没铸卡 ⇒ 传 `false`,体上不带 `retriable`(三条臂同一条律;其余键两种处境逐字相同 —— 同判同答)。
+ * 没有默认值:每个调用点必须说出这件事实。
  */
-export declare function storedBodyReplayAnswer(refusal: StoredBodyReplayRefusal, readerVersion: string): ResumeRefusalAnswer;
+export declare function storedBodyReplayAnswer(refusal: StoredBodyReplayRefusal, readerVersion: string, cardPending: boolean): ResumeRefusalAnswer;
 //# sourceMappingURL=checkpoint-ctx.d.ts.map

package/dist/http/checkpoint-ctx.js

@@ -1,3 +1,4 @@
+import { refusalBody } from "./refusal-body.js";
 export const PERMISSIONS_ALLOW_READINGS = ["allow_layer"];
 export const PERMISSION_MODE_READINGS = ["entry_word"];
 export const ALLOW_LIST_READING_ERAS = ["list", "statement"];
@@ -31,11 +32,10 @@ export function permissionModeReadingStated(ctx) {
 export function permissionModeReadingRefusal() {
     return {
         status: 409,
-        body: {
-            error: "this task was suspended by an earlier server version that re-applied this deployment's AUTONOMY on every resume instead of recording it in the task; this version records the operator's plan floor once, when a task is submitted, so continuing would run this task under the permission mode it was submitted with rather than the one it ran under. Nothing was decided and nothing was resumed, and retrying will be refused the same way: submit the work again as a new task, and if this task is still suspended cancel it first (POST /v1/runs/:id/cancel); to let it finish with read-only hands instead, set AUTONOMY=read-only until it does.",
+        body: refusalBody({
             errorCode: "checkpoint.unsupported_version",
-            retriable: true,
-        },
+            message: "this task was suspended by an earlier server version that re-applied this deployment's AUTONOMY on every resume instead of recording it in the task; this version records the operator's plan floor once, when a task is submitted, so continuing would run this task under the permission mode it was submitted with rather than the one it ran under. Nothing was decided and nothing was resumed, and retrying will be refused the same way: submit the work again as a new task, and if this task is still suspended cancel it first (POST /v1/runs/:id/cancel); to let it finish with read-only hands instead, set AUTONOMY=read-only until it does.",
+        }),
     };
 }
 export function allowListReadingUnstated(ctx) {
@@ -53,20 +53,18 @@ export function allowListReadingRefusal(era) {
         case "list":
             return {
                 status: 409,
-                body: {
-                    error: "this task was suspended by an earlier server version that did not record how it read settings.permissions.allow (7.114.0 and earlier read it as a whitelist: every tool not on the list was refused); this version hands that list to the engine's allow layer, where each entry is a standing yes for the calls it covers, so continuing would give the task more tools than it was submitted with. Nothing was decided and nothing was resumed, and retrying will be refused the same way: submit the work again as a new task, and if this task is still suspended cancel it first (POST /v1/runs/:id/cancel). To allow only certain tools, use the session rules' toolAllow (PUT /v1/sessions/:id/policy) or the request's excludeTools.",
+                body: refusalBody({
                     errorCode: "checkpoint.unsupported_version",
-                    retriable: true,
-                },
+                    message: "this task was suspended by an earlier server version that did not record how it read settings.permissions.allow (7.114.0 and earlier read it as a whitelist: every tool not on the list was refused); this version hands that list to the engine's allow layer, where each entry is a standing yes for the calls it covers, so continuing would give the task more tools than it was submitted with. Nothing was decided and nothing was resumed, and retrying will be refused the same way: submit the work again as a new task, and if this task is still suspended cancel it first (POST /v1/runs/:id/cancel). To allow only certain tools, use the session rules' toolAllow (PUT /v1/sessions/:id/policy) or the request's excludeTools.",
+                }),
             };
         case "statement":
             return {
                 status: 409,
-                body: {
-                    error: "this task was suspended by an earlier server version (7.115.0 to 7.116.x) that read settings.permissions.allow as a statement that the named tools are allowed, which answered only the question nobody else had answered and never cleared an ordinary question such as a file write or a shell command; this version hands that list to the engine's allow layer, where an entry also clears those ordinary questions, so continuing would run calls without asking that the task was submitted to ask about. Nothing was decided and nothing was resumed, and retrying will be refused the same way: submit the work again as a new task, and if this task is still suspended cancel it first (POST /v1/runs/:id/cancel).",
+                body: refusalBody({
                     errorCode: "checkpoint.unsupported_version",
-                    retriable: true,
-                },
+                    message: "this task was suspended by an earlier server version (7.115.0 to 7.116.x) that read settings.permissions.allow as a statement that the named tools are allowed, which answered only the question nobody else had answered and never cleared an ordinary question such as a file write or a shell command; this version hands that list to the engine's allow layer, where an entry also clears those ordinary questions, so continuing would run calls without asking that the task was submitted to ask about. Nothing was decided and nothing was resumed, and retrying will be refused the same way: submit the work again as a new task, and if this task is still suspended cancel it first (POST /v1/runs/:id/cancel).",
+                }),
             };
         default: {
             const unhandled = era;
@@ -77,12 +75,18 @@ export function allowListReadingRefusal(era) {
 export function buildCheckpointVersionKeys(writerVersion, readerVersion) {
     return writerVersion !== undefined ? { writerVersion, readerVersion } : {};
 }
-export function resumeBlockedByPolicyAnswer(message, blockedBy, extra) {
+export function resumeBlockedByPolicyAnswer(inner) {
     return {
         status: 409,
-        body: { error: `resume blocked by an admission policy change: ${message}`, errorCode: "resume_blocked_by_policy", blockedBy, ...(extra ?? {}) },
+        body: refusalBody({ errorCode: "resume_blocked_by_policy", message: `resume blocked by an admission policy change: ${inner.message} — nothing was resumed; if the task is still suspended on its approval, cancel it (POST /v1/runs/:id/cancel) to end it without another model turn`, facts: { blockedBy: inner.errorCode, ...inner.facts } }),
     };
 }
+export function isResumeBlockedByPolicy(answer) {
+    return answer.status === 409 && typeof answer.body === "object" && answer.body !== null && answer.body.errorCode === "resume_blocked_by_policy";
+}
+export function resumeRefusalWithCard(answer, cardPending) {
+    return cardPending ? { status: answer.status, body: { ...answer.body, retriable: true } } : answer;
+}
 export function storedBodyReplayLogFields(refusal) {
     switch (refusal.kind) {
         case "allow_list_reading":
@@ -97,14 +101,17 @@ export function storedBodyReplayLogFields(refusal) {
         }
     }
 }
-export function storedBodyReplayAnswer(refusal, readerVersion) {
+export function storedBodyReplayAnswer(refusal, readerVersion, cardPending) {
+    return resumeRefusalWithCard(storedBodyReplayArmAnswer(refusal, readerVersion), cardPending);
+}
+function storedBodyReplayArmAnswer(refusal, readerVersion) {
     switch (refusal.kind) {
         case "allow_list_reading": {
             const answer = allowListReadingRefusal(refusal.era);
             return { status: answer.status, body: { ...answer.body, ...buildCheckpointVersionKeys(refusal.writerVersion, readerVersion) } };
         }
         case "inert_tool_list":
-            return resumeBlockedByPolicyAnswer(refusal.entry.message, refusal.entry.code, refusal.entry.extra !== undefined ? { ...refusal.entry.extra } : undefined);
+            return resumeBlockedByPolicyAnswer(refusal.entry.extra === undefined ? { errorCode: refusal.entry.code, message: refusal.entry.message } : { errorCode: refusal.entry.code, message: refusal.entry.message, facts: refusal.entry.extra });
         case "permission_mode_reading": {
             const answer = permissionModeReadingRefusal();
             return { status: answer.status, body: { ...answer.body, ...buildCheckpointVersionKeys(refusal.writerVersion, readerVersion) } };