@sema-agent/server 7.147.0 → 7.148.0

package/dist/plugins/workflow-run-store-sql.js

@@ -168,6 +168,16 @@ export class SqlWorkflowRunStore {
 }
 const KIND_SERVED = "served";
 const KIND_PURGE = "purge";
+export async function writeInboxPurgeFenceOn(exec, dialect, sessionId, purgedOwner, now) {
+    const known = purgedOwner !== undefined ? 1 : 0;
+    await exec.query(dialect === "mysql"
+        ? "INSERT INTO workflow_inbox_fence (session_id, kind, run_id, owner, owner_known, until_ms) VALUES (?,?,?,?,?,?) " +
+            "ON DUPLICATE KEY UPDATE owner = VALUES(owner), owner_known = VALUES(owner_known), until_ms = VALUES(until_ms)"
+        : "INSERT INTO workflow_inbox_fence (session_id, kind, run_id, owner, owner_known, until_ms) VALUES ($1,$2,'',$3,$4,$5) " +
+            "ON CONFLICT (session_id, kind, run_id) DO UPDATE SET owner = EXCLUDED.owner, owner_known = EXCLUDED.owner_known, until_ms = EXCLUDED.until_ms", dialect === "mysql"
+        ? [sessionId, KIND_PURGE, "", purgedOwner ?? null, known, now + PURGE_FENCE_MS]
+        : [sessionId, KIND_PURGE, purgedOwner ?? null, known, now + PURGE_FENCE_MS]);
+}
 export class SqlWorkflowCompletionInbox {
     db;
     onWarn;
@@ -241,11 +251,7 @@ export class SqlWorkflowCompletionInbox {
     async purge(sessionId, purgedOwner) {
         const now = Date.now();
         await this.sweepFences(now);
-        await this.db.query(this.q("INSERT INTO workflow_inbox_fence (session_id, kind, run_id, owner, owner_known, until_ms) VALUES (?,?,?,?,?,?) " +
-            "ON DUPLICATE KEY UPDATE owner = VALUES(owner), owner_known = VALUES(owner_known), until_ms = VALUES(until_ms)", "INSERT INTO workflow_inbox_fence (session_id, kind, run_id, owner, owner_known, until_ms) VALUES ($1,$2,'',$3,$4,$5) " +
-            "ON CONFLICT (session_id, kind, run_id) DO UPDATE SET owner = EXCLUDED.owner, owner_known = EXCLUDED.owner_known, until_ms = EXCLUDED.until_ms"), this.db.dialect === "mysql"
-            ? [sessionId, KIND_PURGE, "", purgedOwner ?? null, purgedOwner !== undefined ? 1 : 0, now + PURGE_FENCE_MS]
-            : [sessionId, KIND_PURGE, purgedOwner ?? null, purgedOwner !== undefined ? 1 : 0, now + PURGE_FENCE_MS]);
+        await writeInboxPurgeFenceOn(this.db, this.db.dialect, sessionId, purgedOwner, now);
         await this.db.query(this.q("DELETE FROM workflow_completion_inbox WHERE session_id = ?", "DELETE FROM workflow_completion_inbox WHERE session_id = $1"), [sessionId]);
     }
     async markTerminalServed(sessionId, runId) {

package/dist/principal-jwt.d.ts

@@ -1,5 +1,6 @@
 import type { ApprovalHmacKey, PrincipalJwtKey } from "./auth-keys.js";
 import { type ApprovalEnvelope } from "./approval-hmac.js";
+import { type Person } from "./owner-brands.js";
 /**
  * 验签允许的**时钟不一致容差**(秒)—— 本仓这条轴上的单一来源。
  *
@@ -45,8 +46,6 @@ export declare function verifyPrincipalJwt(token: string, keys: PrincipalJwtKey[
  * 形:`sha256(utf8(editedPlan))` hex —— 与 `approvalBnd` 同摘要、同编码;逐字节,不归一化(签名器与 worker
  * 必须对同一串字节达成一致,任何"归一化"都是第二个写者)。
  */
-/** 良构 Unicode(无孤立代理项)。`u` 旗下配对代理项是一个码点、不匹配 `\p{Surrogate}`;只有孤立的才命中。 */
-export declare function isWellFormedUnicode(s: string): boolean;
 export declare function editedPlanBinding(editedPlan: string): string;
 /**
  * JWT `cnf.bnd` = **「这份身份凭据被签发去决哪一张卡」**(动作身份),故只哈希前三位。
@@ -79,10 +78,11 @@ export interface SingleUseProof {
      */
     readonly acceptedBeforeMs: number;
 }
-/** {@link verifyDirectDoorProof} 的判决。`singleUse` 在场 = 调用方必须在改任何状态**之前**消费它一次。 */
+/** {@link verifyDirectDoorProof} 的判决。`singleUse` 在场 = 调用方必须在改任何状态**之前**消费它一次。`principal` = 这一次决定的证明推出的人
+ *  (带 `Person` 品牌:本函数是它的铸点之一 —— 决定口用它替换请求身份,`http/owner-access.ts` 的 `callerOfDecision` 按请求的场景铸决定者的主体)。 */
 export type DirectDoorProofResult = {
     ok: true;
-    principal: string;
+    principal: Person;
     singleUse?: SingleUseProof;
 } | {
     ok: false;

package/dist/principal-jwt.js

@@ -1,5 +1,7 @@
 import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
 import { verifyApprovalHmac } from "./approval-hmac.js";
+import { mintPerson } from "./owner-brands.js";
+import { PRINCIPAL_MAX_BYTES, isWellFormedUnicode, principalShapeProblem } from "./principal-shape.js";
 export const PRINCIPAL_JWT_CLOCK_SKEW_SEC = 30;
 function b64urlToBuf(s) {
     return Buffer.from(s, "base64url");
@@ -72,9 +74,6 @@ export function verifyPrincipalJwt(token, keys, expect) {
     const bnd = typeof payload.cnf?.bnd === "string" ? payload.cnf.bnd : undefined;
     return { sub: payload.sub, bnd, acceptedBeforeMs: (Math.floor(payload.exp + skew) + 1) * 1000 };
 }
-export function isWellFormedUnicode(s) {
-    return !/\p{Surrogate}/u.test(s);
-}
 export function editedPlanBinding(editedPlan) {
     if (!isWellFormedUnicode(editedPlan))
         throw new Error("editedPlanBinding: editedPlan is not well-formed Unicode (lone surrogate) — utf8 hashing would be lossy");
@@ -104,8 +103,24 @@ export function verifyDirectDoorProof(proof, envelope, config, opts) {
     const ok = verifyApprovalHmac(envelope, proof.mac, proof.kid, config.approvalHmacKeys);
     if (!ok)
         return { ok: false, status: 401, errorCode: "approval_mac_invalid", error: "approval envelope MAC invalid" };
+    const shape = principalShapeProblem(verified.sub);
+    switch (shape) {
+        case undefined:
+            break;
+        case "not_a_name":
+            return { ok: false, status: 400, errorCode: "principal_not_a_name", error: "principal token subject is not a principal name — the issuer must sign a visible-character identity" };
+        case "reserved":
+            return { ok: false, status: 400, errorCode: "principal_reserved", error: "principal token subject is a reserved identifier (an internal scope sentinel or a scenario subject) — the issuer must sign the person's own identifier" };
+        case "too_long":
+            return { ok: false, status: 400, errorCode: "principal_too_long", error: `principal token subject exceeds ${PRINCIPAL_MAX_BYTES} UTF-8 bytes` };
+        default: {
+            const unknownShape = shape;
+            throw new Error(`verifyDirectDoorProof: unknown principal shape problem ${String(unknownShape)}`);
+        }
+    }
+    const principal = mintPerson(verified.sub);
     return actionBinding
-        ? { ok: true, principal: verified.sub }
-        : { ok: true, principal: verified.sub, singleUse: { nonce: envelope.boundCallId, acceptedBeforeMs: verified.acceptedBeforeMs } };
+        ? { ok: true, principal }
+        : { ok: true, principal, singleUse: { nonce: envelope.boundCallId, acceptedBeforeMs: verified.acceptedBeforeMs } };
 }
 //# sourceMappingURL=principal-jwt.js.map

package/dist/principal-shape.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 🔴 **主体长度的唯一定义:至多这么多个 UTF-8 字节。** 凡判「这只串当不当得了主体 / 主体身份键」的长度,一律读它、按字节数(`Buffer.byteLength(s, "utf8")`):
+ * 本文件的判官、收件箱的键判官(收件箱 scope 就是主体)、记忆退出名单的判、两处运维 `?scope=` 查询、规则面的运维目标、配额三表两方言的身份列宽。
+ * 为什么是字节:主体原样落进的最窄一类列是按字节计宽的 `VARBINARY(190)`(收件箱 / 后台子代 / 名册的键列);按字符计宽的 `VARCHAR(190)`(TiDB utf8mb4 与 PG
+ * 都数码点)装得下任何 190 字节的串(一个码点至少一个字节)。所以 190 字节 ≤ 「190 家族」每一只主体列,升到本尺不需要改任何既有列。
+ * 不同源的 190(会话 / run / 工具调用 id 列的历史宽度惯例、断路器键、跨会话信封来源位、编码后的记忆 scope 列、令牌 scope 声明)不读本常量。
+ */
+export declare const PRINCIPAL_MAX_BYTES = 190;
+/**
+ * 良构 Unicode(无孤立代理项)的唯一判式 —— 主体名判官的一格(下面),也是收件箱键判官与编辑计划绑定摘要的同一读法(住在叶子里,三处都能值导入、不成环)。
+ * `u` 旗下配对代理项是一个码点、不匹配 `\p{Surrogate}`;只有孤立的才命中。
+ */
+export declare function isWellFormedUnicode(s: string): boolean;
+/** 修1 — the SINGLE registry of internal sentinel/scope identifiers a tenant principal must never equal.
+ *  🔴 新增内部 sentinel scope 必须在此登记(精确值加 RESERVED_PRINCIPALS,前缀族加
+ *  RESERVED_PRINCIPAL_PREFIXES),否则 assertPrincipalShape 会放行同名租户 = 与内部 scope 行合流的超范围面。
+ *  Current entries (where each is minted): `"_"` = single-user/anonymous sentinel (checkpoint/sendfile/
+ *  resource-suspend scope family); `"__none__"` = the missing-principal read placeholder of the approval
+ *  queue faces up to 7.132.x (7.133.0 reads the anonymous group `"_"` instead; still reserved because a 7.132.x replica in the same
+ *  rolling upgrade lists that scope for anonymous callers, so a tenant by that name would merge with them there); `"_leader"` = leader durable-approval scope
+ *  (src/leader/wire.ts); prefix `"_leader-"` = the leader resource-suspend scope family
+ *  (`_leader-resource-<workerId>`, src/leader/wire.ts); prefix `"_orphan:"` = the owner written on a delegated session whose
+ *  delegation ancestors are gone (`_orphan:<sessionId>`, src/delegated-session-owner.ts) — a caller allowed to authenticate as it
+ *  would read that transcript; prefix `"_scn:"` = a subject that carries a scenario (`_scn:<scenario>:<person>`, `owner-brands.ts` `subjectOf`) —
+ *  a caller allowed to authenticate as it would BE another person's scenario partition. NB the `_leader-` prefix REQUIRES the hyphen — a tenant named
+ *  `_leaderX` collides with nothing internal and stays valid (boundary pinned by test). */
+export declare const RESERVED_PRINCIPALS: readonly string[];
+export declare const RESERVED_PRINCIPAL_PREFIXES: readonly string[];
+/** The principal-shape rule as a VERDICT (the one judge; {@link assertPrincipalShape} is its throwing reader). `undefined` = a
+ *  principal may carry this string; otherwise which rule it breaks. A reader that only needs "can this string be anyone?" (the
+ *  organization delivery gate's recipient: a string that breaks the rule is nobody, refused with the same bytes as an unknown
+ *  principal) reads the verdict instead of catching the throw.
+ *
+ *  Order: "is it a name at all" first — the other two rules presuppose a name (a reserved identifier / a name too wide for the
+ *  column), and the `reserved` sentence echoes the value while the `not_a_name` sentence never does (a string that names nobody may be a
+ *  pasted credential). An empty string is `not_a_name` here (the engine's judge says so); so is a string that is not well-formed Unicode (a lone
+ *  surrogate is no character). A header reader that treats a blank header as "no principal" decides that before asking. `too_long` counts UTF-8 bytes
+ *  ({@link PRINCIPAL_MAX_BYTES}). */
+export type PrincipalShapeProblem = "not_a_name" | "reserved" | "too_long";
+export declare function principalShapeProblem(principal: string): PrincipalShapeProblem | undefined;
+//# sourceMappingURL=principal-shape.d.ts.map

package/dist/principal-shape.js

@@ -0,0 +1,19 @@
+import { principalNameOf } from "@sema-agent/core";
+import { ORPHAN_SESSION_OWNER_PREFIX } from "./delegated-session-owner.js";
+import { SCENARIO_SUBJECT_PREFIX } from "./owner-brands.js";
+export const PRINCIPAL_MAX_BYTES = 190;
+export function isWellFormedUnicode(s) {
+    return !/\p{Surrogate}/u.test(s);
+}
+export const RESERVED_PRINCIPALS = ["_", "__none__", "_leader"];
+export const RESERVED_PRINCIPAL_PREFIXES = ["_leader-", ORPHAN_SESSION_OWNER_PREFIX, SCENARIO_SUBJECT_PREFIX];
+export function principalShapeProblem(principal) {
+    if (principalNameOf(principal) === undefined || !isWellFormedUnicode(principal))
+        return "not_a_name";
+    if (RESERVED_PRINCIPALS.includes(principal) || RESERVED_PRINCIPAL_PREFIXES.some((p) => principal.startsWith(p)))
+        return "reserved";
+    if (Buffer.byteLength(principal, "utf8") > PRINCIPAL_MAX_BYTES)
+        return "too_long";
+    return undefined;
+}
+//# sourceMappingURL=principal-shape.js.map

package/dist/question.d.ts

@@ -1,4 +1,5 @@
 import { type AskQuestionRequest, type OnQuestionOutcome, type QuestionAnswer, type AskQuestion } from "@sema-agent/core";
+import { type HitlTransport } from "./hitl-delivery.js";
 /** A live question frame delivered to whoever tails this run's stream. `type` IS the SSE event name (mirrors the
  *  named-event convention; the payload also carries `type` so a proxy that strips event names still works). The shell
  *  renders `question` as a dialog and dismisses on `question_complete`. */
@@ -23,30 +24,20 @@ export interface QuestionFrame {
     /** "question" only: `serverNowMs + expiresInMs` — absolute deadline on the server's clock. */
     expiresAtMs?: number;
 }
-/** The per-run context `onQuestion` recovers via ALS. `emit` delivers a frame to the run's stream; `abortSignal`
- *  (the run's own cancel signal) releases a question parked awaiting a human when the run aborts.
+/** The per-run context `onQuestion` recovers via ALS. `transport` = the leg's ONE HITL transport (shared with the elicitation
+ *  and approval contexts of the same leg; `hitl-delivery.ts` owns the law: ledger first, then live — a frame the ledger
+ *  cannot take never reaches the live face). `abortSignal` (the run's own cancel signal) releases a question parked
+ *  awaiting a human when the run aborts.
  *
- *  🔴 ONE LAW for every leg: a question frame that enters a run's stream has a LEDGER TWIN (the row
- *  `GET /v1/runs/:id/events` replays — a page reload recovers the open card from it); the leg decides only whether it
- *  ALSO writes a live socket. The background leg has no socket, so its `emit` IS the durable append; the synchronous
- *  stream leg lands the same frame in the ledger first and then writes the SSE connection (`createLedgerTwinEmit`).
  *  The ledger carries the CARD, not the answer door: `POST /v1/questions/:id/respond` stays live-only (this replica's
- *  memory, `ttlMs`), so a replayed card is answerable only until its own `expiresAtMs` and only on this replica. */
+ *  memory, `ttlMs`), so a replayed card is answerable only until its own `expiresAtMs` and only on this replica.
+ *  The adjudication probe ({@link QuestionCoordinator.hasLiveContext}) reads the same transport's `reachable()` — one
+ *  reading of "can this leg's face show a card right now?". */
 export interface QuestionRunContext {
     taskId: string;
     owner: string | null;
-    emit: (frame: QuestionFrame) => void | Promise<void>;
+    transport: HitlTransport<QuestionFrame>;
     abortSignal?: AbortSignal;
-    /** OPTIONAL reachability predicate for this leg's LIVE delivery face — one reading, two consumers:
-     *  {@link QuestionCoordinator.hasLiveContext} (the park-vs-live adjudication probe) and the OPEN frame itself (a face
-     *  that cannot show the card right now refuses the ask on the spot, the same failed-delivery arm, instead of parking it
-     *  to TTL on a ledger row nobody is watching). CONSTRAINT: a leg whose face can go away WHILE the leg keeps running MUST
-     *  supply it — `/v1/tasks/stream` under `x-detach-on-disconnect: true` keeps executing inside this ALS scope after the
-     *  client left. Without the predicate the adjudication would read "live" and hand the leg to a face nobody can reach.
-     *  ABSENT ⇒ always reachable, which is exactly right for the background leg (its face IS the durable events tail,
-     *  readable whenever a client attaches). The CLOSE frame never asks it: it is a record, and it lands in the ledger twin
-     *  whether or not the socket is still there. */
-    deliverable?: () => boolean;
 }
 /** The per-run question window the deployment owns (core caps nothing). Env: `QUESTION_MAX_CONCURRENT_PER_RUN` /
  *  `QUESTION_MAX_TOTAL_PER_RUN` / `QUESTION_TTL_MS` (see `ServiceConfig.questionThrottle`). */
@@ -91,7 +82,7 @@ export declare class QuestionCoordinator {
     question: (req: AskQuestionRequest, signal?: AbortSignal) => Promise<OnQuestionOutcome>;
     /** `POST /v1/questions/:id/respond` — resolve a parked question with the shell's answer. Owner-gated with a 404 (no
      *  existence oracle): a non-owner AND an unknown id (answered / expired / wrong replica) both get 404. Returns the
-     *  HTTP {status, body}; the HTTP layer owns auth (gatedPrincipal + REQUIRE_PRINCIPAL) before calling. */
+     *  HTTP {status, body}; the HTTP layer owns auth (gatedSubject + REQUIRE_PRINCIPAL) before calling. */
     respond(id: string, principal: string | undefined, body: unknown): {
         status: number;
         body: unknown;
@@ -103,10 +94,9 @@ export declare class QuestionCoordinator {
      *  resolve-spec 的 durable question policy 用它在**判决时**分腿:有活流 ⇒ allow(问活人),无 ⇒
      *  ask(durable park)。ALS 让这个判断天然 per-leg,policy 组装期不必预知腿别。
      *  🔴 判据是「投递面此刻可达」而不只是「ALS 在场」(复审 A1):detach 腿断连后 run 仍在本作用域里跑,
-     *  只判 ALS 会把一条谁也收不到的问题判成 allow——挂满 ttl 后以 unavailable 结算,非 durable 形 core
-     *  就此合成续跑,活人再没机会答;而 park 才是它该走的腿。
-     *  谓词缺席 ⇒ 恒可达(后台腿的 durable events tail 语义)。谓词本身抛错按不可达处理:判决面
-     *  fail-closed 到 park(park 可由运维补答,续跑掉的问题不可回收)。 */
+     *  只判 ALS 会把一条谁也收不到的问题判成 allow;park 才是它该走的腿。读的是本腿传输的 `reachable()`
+     *  (有直写面 ⇒ 直写此刻活着;只有账本 ⇒ 恒真,后台腿的 durable events tail 语义;谓词读不出 ⇒ 假,判决面 fail-closed 到 park)。
+     *  只服务判决面:判决放行之后的开帧投递只读传输律(有账本的腿上死直写 = 卡在账本里,送到)。 */
     hasLiveContext(): boolean;
     private countersFor;
 }

package/dist/question.js

@@ -3,17 +3,9 @@ import { uuidv7 } from "@sema-agent/core";
 import { redactDeep } from "./trace/redact.js";
 import { recordFailOpen } from "./observability/fail-open.js";
 import { refusalBody } from "./http/refusal-body.js";
+import { keyAdmits, ownerCellOf, recoveredSubject } from "./owner-faces.js";
+import { createHitlOpenRace } from "./hitl-delivery.js";
 const MAX_QUESTIONS_BYTES = 16384;
-function isFaceReachable(ctx) {
-    if (ctx.deliverable === undefined)
-        return true;
-    try {
-        return ctx.deliverable();
-    }
-    catch {
-        return false;
-    }
-}
 export const DEFAULT_QUESTION_THROTTLE = {
     maxConcurrentPerRun: 2,
     maxTotalPerRun: 20,
@@ -113,39 +105,29 @@ export class QuestionCoordinator {
         signal?.addEventListener("abort", onAbort, { once: true });
         ctx.abortSignal?.addEventListener("abort", onAbort, { once: true });
         this.pending.set(id, { settle, owner: ctx.owner, taskId: ctx.taskId });
-        const emitted = (async () => {
-            if (!isFaceReachable(ctx))
-                throw new Error("question delivery face unreachable — the open frame has nobody to show it to");
-            const now = Date.now();
-            await ctx.emit({ type: "question", questionId: id, questions, serverNowMs: now, expiresInMs: this.throttle.ttlMs, expiresAtMs: now + this.throttle.ttlMs });
-            return isFaceReachable(ctx) ? "ok" : "landed-face-gone";
-        })()
-            .then((r) => r, () => "failed");
-        const delivery = await Promise.race([emitted, answerP.then(() => "stalled")]);
-        if (delivery === "ok" || delivery === "landed-face-gone") {
+        const now = Date.now();
+        const race = createHitlOpenRace({
+            targets: [{ transport: ctx.transport, frame: { type: "question", questionId: id, questions, serverNowMs: now, expiresInMs: this.throttle.ttlMs, expiresAtMs: now + this.throttle.ttlMs } }],
+            settled: answerP,
+        });
+        const phase = await race.phase;
+        if (phase === "delivered") {
             rc.total += 1;
-            if (delivery === "landed-face-gone") {
-                recordFailOpen("server.question.open-frame-undelivered", `question=${id} face-gone-while-landing`);
-                settle(UNAVAILABLE, "unanswered");
-            }
         }
-        else if (delivery === "failed") {
+        else if (phase === "undelivered") {
             recordFailOpen("server.question.open-frame-undelivered", `question=${id}`);
             settle(UNAVAILABLE, "unanswered");
         }
-        const answer = await answerP;
-        void emitted
-            .then((result) => {
-            if (result === "failed") {
-                if (delivery === "stalled")
+        else {
+            void race.landing.then((late) => {
+                if (late === "delivered")
+                    rc.total += 1;
+                else
                     recordFailOpen("server.question.open-frame-undelivered", `question=${id}`);
-                return undefined;
-            }
-            if (delivery === "stalled")
-                rc.total += 1;
-            return ctx.emit({ type: "question_complete", questionId: id, outcome: lastOutcome, serverNowMs: Date.now() });
-        })
-            .catch(() => recordFailOpen("server.question.complete-breadcrumb-dropped", `question=${id}`));
+            });
+        }
+        const answer = await answerP;
+        race.close({ type: "question_complete", questionId: id, outcome: lastOutcome, serverNowMs: Date.now() });
         return answer;
     };
     respond(id, principal, body) {
@@ -153,7 +135,7 @@ export class QuestionCoordinator {
         if (!parsed.ok)
             return { status: 400, body: refusalBody({ errorCode: "request.body_shape", message: parsed.error }) };
         const entry = this.pending.get(id);
-        if (!entry || (entry.owner !== null && entry.owner !== principal)) {
+        if (!entry || !keyAdmits("ask.answer", { subject: recoveredSubject(principal), operator: false }, ownerCellOf(entry.owner))) {
             return { status: 404, body: refusalBody({ errorCode: "question.not_pending", message: "no pending question for this id (answered, expired, or not on this replica)" }) };
         }
         entry.settle(parsed.value, "answered");
@@ -164,7 +146,7 @@ export class QuestionCoordinator {
     }
     hasLiveContext() {
         const ctx = this.als.getStore();
-        return ctx !== undefined && isFaceReachable(ctx);
+        return ctx !== undefined && ctx.transport.reachable();
     }
     countersFor(taskId) {
         let rc = this.counters.get(taskId);

package/dist/request-declaration-refusal.d.ts

@@ -6,11 +6,16 @@
  *  ① **列表**:在场却不是数组 / 超过挂载上限 / 某一条不是对象 ⇒ `400 request.field_invalid`(整份拒而不是挂前 N 条 / 摘掉读不出的那条:一份被悄悄截短的声明,在发送方那里读起来是「生效了」);
  *     超上限用撞帽的唯一铸点({@link limitRefusal}),拒体带机读位一组键(`field` · `reason:"over_cap"` · `count` · `cap`);
  *  ② **键名**:条目层的词表外键 ⇒ `400 request.body_shape` + `unknownKeys`(句子由各座自己写 —— 受理键表与嵌套层是座位自己的事);
- *  ③ **键值**:每个受理键一只判官 ⇒ `400 request.field_invalid`,句子 `<坐标>.<键路径> (<subject> "<名>") is not a usable declaration — <判官原因句>. …`,不回显值;
+ *  ③ **键值**:每个受理键一只判官 ⇒ `400 request.field_invalid`,句子 `<坐标>.<键路径>[ (<条目指认>)] is not a usable declaration — <判官原因句>. …`(条目指认由座位给:有申报名的座位 `(server "<名>")`,没有名字的座位不带),不回显值;
  *     判官答「URL 带凭据」时拒体另带机读位 `field` / `reason`({@link urlCredentialFacts})。
  * 第一处坏形即答:先列表、后条目;条目里先键名、后键值。各座只写**自己的**两件事:受理键表 + 键值判官表(以及它自己的词表外键句)。拒形、句尾、撞帽句不在座位文件里手拼 ——
  * 两份手拼的拒形迟早分岔(`a2aPeers` 上线时就是缺了这一整套,坏形换回 200 + 运维 warn,调用方以为声明生效了)。
  *
+ * ## 机读位(`request.field_invalid` 的每一只拒都带)
+ * 列表级与条目级的 `request.field_invalid` 拒体恒带 `field`(体内坐标:列表键 / `<列表>[i]` / `<列表>[i].<键路径>`),条目级(含条目不是对象)另带 `index`(条目在列表里的下标);撞帽那一形仍是撞帽的一组键,
+ * URL 带凭据那一形在 `field` / `reason` 之外同带 `index`。机读位只在这里铸:判官({@link DeclarationKeyJudge})只交原因,`field` 由原因的键路径铸、`index` 由骨架的循环铸 —— 座位与判官不手拼坐标。
+ * `request.body_shape` 的词表外键拒另有自己的机读位(`unknownKeys`,全坐标),不在这一组。
+ *
  * ## 射程
  * 纯值域、与租户车道无关;只在 fresh 提交腿上问(`boot/resolve-spec.ts` 的 `opts.leg`):重放存量 body 的腿走宽容读器,一个 4xx 打在 resume 上会永久砖死一条 parked 任务。
  */
@@ -19,26 +24,44 @@ import { type LimitFacts } from "./limit-refusal.js";
 import { type UrlCredentialFacts } from "./url-credential-refusal.js";
 /** 一座声明列表的名字与上限、以及拒句里要用的称呼(座位的常量,铸点只读)。 */
 export interface DeclarationSeat {
-    /** 请求体里这张列表的键,也是机读坐标的根(`mcpServers` | `a2aPeers`)。 */
+    /** 请求体里这张列表的键,也是机读坐标的根(`mcpServers` | `a2aPeers` | `images`)。 */
     readonly list: string;
     /** 挂载上限(条数;超过 ⇒ 撞帽拒)。 */
     readonly cap: number;
-    /** 一条声明所声明的东西(拒句里的单数名词:`server` | `peer`)。 */
-    readonly subject: string;
+    /** 条目级拒句里条目的指认(带前导空格,接在坐标后):有申报名的座位 = ` (server "<名>")`;坐标本身唯一的座位(没有名字的条目)= 空串。 */
+    readonly identify: (entry: Record<string, unknown>) => string;
+    /** 条目级拒句的收尾句:说清「为什么整份请求被拒、而不是照坏条目办」与出路。 */
+    readonly entryTail: string;
     /** 「一条声明」的整称(`an MCP server declaration`)。 */
     readonly declaration: string;
     /** 「多条声明」的整称(`MCP server declarations`)。 */
     readonly declarations: string;
 }
+/** 有申报名、挂在一个外部服务上的座位(`mcpServers` · `a2aPeers`)的座位常量:指认 = ` (<subject> "<名>")`,收尾句说「不挂就跑偏」。`subject` = 一条声明所声明的东西(`server` | `peer`)。 */
+export declare function createMountSeat(o: {
+    readonly list: string;
+    readonly cap: number;
+    readonly subject: string;
+    readonly declaration: string;
+    readonly declarations: string;
+}): DeclarationSeat;
 /** 一次拒绝:码 + 句 + 词表外的键名表(只在闭集那一形上在场)+ 机读位(撞帽 / URL 带凭据两形上在场)。受理口(同步 400)与探测口(`POST …/probe`)原样转述同一份。 */
 export interface DeclarationRefusal {
     readonly errorCode: "request.body_shape" | "request.field_invalid";
     readonly message: string;
     /** 词表外的键,全路径形(已清洗 + 截长 + 排序 + 封顶)。 */
     readonly unknownKeys?: readonly string[];
-    /** 撞帽:`field` · `reason:"over_cap"` · `count` · `cap`;URL 带凭据:`field` · `reason`(判官的拒因词)。 */
-    readonly facts?: UrlCredentialFacts | LimitFacts;
+    /** 机读位:撞帽 = `field` · `reason:"over_cap"` · `count` · `cap`;URL 带凭据 = `field` · `reason`(判官的拒因词)· `index`;其余 `request.field_invalid` = `field`(条目级另带 `index`)。 */
+    readonly facts?: DeclarationEntryFacts | LimitFacts;
 }
+/** 条目判官(座位的 `judgeEntry` · 键值判官表)交回的拒:机读位只会是条目级的那一组({@link DeclarationEntryFacts}),撞帽那一形只由骨架的列表级铸 —— 所以补 `index` 的函数收窄到这一型,不靠运行期猜。 */
+export type EntryRefusal = Omit<DeclarationRefusal, "facts"> & {
+    readonly facts?: DeclarationEntryFacts;
+};
+/** 列表级 / 条目级 `request.field_invalid` 拒的机读位:`field` 恒在;`index` = 条目级才有(条目在列表里的下标);URL 带凭据那一形另带判官的拒因词 `reason`。 */
+export type DeclarationEntryFacts = (Pick<UrlCredentialFacts, "field"> | UrlCredentialFacts) & {
+    readonly index?: number;
+};
 /** 一处键值坏形:键路径(相对条目)+ 判官的原因句;答「URL 带凭据」时另带判官的答案(⇒ 拒体带机读位)。 */
 export interface DeclarationKeyIssue {
     readonly path: string;
@@ -55,8 +78,8 @@ export declare function declaredName(e: unknown): string;
 export declare function declarationNameIssue(entry: Record<string, unknown>): DeclarationKeyIssue | undefined;
 /** 列表级拒句的收尾句:说清「为什么整份被拒、而不是只按读得出的那部分办」与出路(空列表 = 什么都不声明)。 */
 export declare const LIST_REFUSAL_TAIL: string;
-/** 列表级的一处坏形 → 拒(码恒 `request.field_invalid`)。`head` 只说位置与形的**种类**,不回显值。 */
-export declare function declarationListRefusal(head: string): DeclarationRefusal;
+/** 列表级的一处坏形 → 拒(码恒 `request.field_invalid`,体带 `field`)。`head` 只说位置与形的**种类**,不回显值;`field` = 坏形所在的体内坐标(列表键 / `<列表>[i]`)。 */
+export declare function declarationListRefusal(head: string, field: string): EntryRefusal;
 /**
  * 一处键值坏形**怎么被说出来**:体内坐标(`<条目坐标>.<键路径>`)+ 判官的原因句(只剥控制与双向字符,不回显值)。受理口的拒句与读器的丢弃因(请求腿运维 warn 的 `field` / `reason`)读**这一只** ——
  * 原因只来自判官表,组句只在这里(两边各写一份,迟早分岔)。
@@ -78,17 +101,17 @@ export declare function declarationOverCapFacts(seat: DeclarationSeat, count: nu
  * 「什么算对象」只在这里判。
  */
 export declare function declarationEntryNotObject(seat: DeclarationSeat, entry: unknown, at: string): string | undefined;
-/** 一处键值坏形 → 拒。**所有键同一个形**;条目名过唯一的回显清洗,读不出名字的条目用占位,坐标与原因句由 {@link declarationIssueFacts} 铸。 */
-export declare function declarationFieldRefusal(seat: DeclarationSeat, entry: Record<string, unknown>, at: string, issue: DeclarationKeyIssue): DeclarationRefusal;
+/** 一处键值坏形 → 拒。**所有键同一个形**;条目指认由座位给({@link DeclarationSeat.identify}),坐标与原因句由 {@link declarationIssueFacts} 铸,机读位 `field`(判官答 URL 带凭据时另带 `reason`)与句子点名同一个坐标。 */
+export declare function declarationFieldRefusal(seat: DeclarationSeat, entry: Record<string, unknown>, at: string, issue: DeclarationKeyIssue): EntryRefusal;
 /** 一条条目的键值判官表按受理键序问一遍,第一处坏形即返回。 */
 export declare function judgeDeclarationKeys<K extends string, E extends Record<string, unknown>>(seat: DeclarationSeat, entry: E, at: string, keys: readonly K[], judges: {
     readonly [P in K]: DeclarationKeyJudge<E>;
-}): DeclarationRefusal | undefined;
+}): EntryRefusal | undefined;
 /**
  * 一张声明列表「能不能原样用」的回答者骨架:列表级(缺席 / `null` ⇒ 没声明;不是数组 / 超上限 / 条目不是对象)在这里,条目级交座位的 `judgeEntry`(词表外的键 → 键值)。
  * `undefined` = 能原样用(或没声明;各门自己定缺席的意思)。
  */
-export declare function requestDeclarationRefusal(seat: DeclarationSeat, list: unknown, judgeEntry: (entry: Record<string, unknown>, at: string) => DeclarationRefusal | undefined): DeclarationRefusal | undefined;
+export declare function requestDeclarationRefusal(seat: DeclarationSeat, list: unknown, judgeEntry: (entry: Record<string, unknown>, at: string) => EntryRefusal | undefined): DeclarationRefusal | undefined;
 /** 受理口的转述:有答案 ⇒ 同步 400(码 / 句 / `unknownKeys` / 机读位原样);没有 ⇒ 什么也不做。 */
 export declare function throwDeclarationRefusal(refusal: DeclarationRefusal | undefined): void;
 //# sourceMappingURL=request-declaration-refusal.d.ts.map

package/dist/request-declaration-refusal.js

@@ -3,6 +3,16 @@ import { createCodedHttpError } from "./security.js";
 import { limitRefusal } from "./limit-refusal.js";
 import { echoKeyName } from "./request-key-closure.js";
 import { urlCredentialFacts } from "./url-credential-refusal.js";
+export function createMountSeat(o) {
+    return {
+        list: o.list,
+        cap: o.cap,
+        identify: (entry) => ` (${o.subject} "${echoKeyName("", declaredName(entry))}")`,
+        entryTail: mountedEntryTail(o.subject),
+        declaration: o.declaration,
+        declarations: o.declarations,
+    };
+}
 export const MALFORMED_NAME = "<malformed>";
 export function declaredName(e) {
     return e && typeof e === "object" && typeof e.name === "string" && e.name !== ""
@@ -14,10 +24,10 @@ export function declarationNameIssue(entry) {
 }
 export const LIST_REFUSAL_TAIL = "The request is refused rather than acting on part of the list: declarations that silently did not apply would read as in effect to whoever sent them. " +
     "Fix the list (an empty list declares none).";
-export function declarationListRefusal(head) {
-    return { errorCode: "request.field_invalid", message: `${head}. ${LIST_REFUSAL_TAIL}` };
+export function declarationListRefusal(head, field) {
+    return { errorCode: "request.field_invalid", message: `${head}. ${LIST_REFUSAL_TAIL}`, facts: { field } };
 }
-function entryRefusalTail(subject) {
+function mountedEntryTail(subject) {
     return (`The request is refused rather than mounting the ${subject} without it: a declaration that silently did not apply would leave the ${subject} running differently from what you declared. ` +
         "Fix the entry (an optional key may also be omitted).");
 }
@@ -32,14 +42,16 @@ export function declarationEntryNotObject(seat, entry, at) {
     return entry === null || typeof entry !== "object" || Array.isArray(entry) ? `${at} is ${describeValueShape(entry)}, not ${seat.declaration} (an object)` : undefined;
 }
 export function declarationFieldRefusal(seat, entry, at, issue) {
-    const name = echoKeyName("", declaredName(entry));
     const { field, reason } = declarationIssueFacts(at, issue);
     return {
         errorCode: "request.field_invalid",
-        message: `${field} (${seat.subject} "${name}") is not a usable declaration — ${reason}. ${entryRefusalTail(seat.subject)}`,
-        ...(issue.credential === undefined ? {} : { facts: urlCredentialFacts(`${at}.${issue.path}`, issue.credential) }),
+        message: `${field}${seat.identify(entry)} is not a usable declaration — ${reason}. ${seat.entryTail}`,
+        facts: issue.credential === undefined ? { field } : urlCredentialFacts(field, issue.credential),
     };
 }
+function withEntryIndex(refusal, index) {
+    return refusal.errorCode === "request.field_invalid" && refusal.facts !== undefined ? { ...refusal, facts: { ...refusal.facts, index } } : refusal;
+}
 export function judgeDeclarationKeys(seat, entry, at, keys, judges) {
     for (const key of keys) {
         const issue = judges[key](entry, at);
@@ -52,7 +64,7 @@ export function requestDeclarationRefusal(seat, list, judgeEntry) {
     if (list === undefined || list === null)
         return undefined;
     if (!Array.isArray(list))
-        return declarationListRefusal(`${seat.list} is ${describeValueShape(list)}, not an array of ${seat.declarations}`);
+        return declarationListRefusal(`${seat.list} is ${describeValueShape(list)}, not an array of ${seat.declarations}`, seat.list);
     if (list.length > seat.cap) {
         const capped = limitRefusal(seat.list, "entries", list.length, seat.cap, { tail: LIST_REFUSAL_TAIL });
         return { errorCode: "request.field_invalid", message: capped.message, facts: capped.facts };
@@ -62,10 +74,10 @@ export function requestDeclarationRefusal(seat, list, judgeEntry) {
         const at = `${seat.list}[${i}]`;
         const notObject = declarationEntryNotObject(seat, entry, at);
         if (notObject !== undefined)
-            return declarationListRefusal(notObject);
+            return withEntryIndex(declarationListRefusal(notObject, at), i);
         const refusal = judgeEntry(entry, at);
         if (refusal !== undefined)
-            return refusal;
+            return withEntryIndex(refusal, i);
     }
     return undefined;
 }

package/dist/request-form.d.ts

@@ -0,0 +1,58 @@
+/**
+ * **请求形的拒** —— 一条律:门先于铸。
+ *
+ * 一次提交里,判据只读**请求本身**(体 · 头里验过的主体 · 到达的腿)与**进程期不变的部署配置**(车道、主体姿态、运维旋钮 —— 不是热应用的模型面)就答得出的拒,
+ * 在授权器铸下任何会话行之前答(受理漏斗 `http/admission.ts` 调 {@link assertRequestFormBeforeMint}):会话店零写、撤回出口零次,壳的 `--resume` 清单里不会出现这次提交。
+ * 铸点之后剩下的拒,判据都要读状态 —— 会话行与它的放置、店里的内容、装配器自己装配的事实(锁集、数据根、店的接线)、热应用的模型面、主体的中心裁定、在飞状态、引擎 ——
+ * 由提交出口(`submission-exit.ts`)在终局应答之前条件撤回收场。两类不交,也没有第三类。
+ *
+ * 分类的单位是**拒绝点**(一处拒与守着它的判据),只看判据的输入,不看它今天住在哪一段。本文件的判官在铸点之前答过,装配器(`boot/resolve-spec.ts`)对同一只判官的复判读同一份输入
+ * (受理门交给装配器的那一份体 · 同一只 `ServiceConfig` 的不变字段 · 按请求记忆化的主体),答同一个结论 —— 那一读是续跑重放腿与直调嵌入方的门(它们不经受理漏斗),
+ * 在 HTTP 新提交腿上恒不拒。
+ *
+ * 句与码的唯一属主是各判官;本文件把装配器里原先内联的几只判(`inheritEnv` 的车道与射程、工具名清单读成空、附件句柄形、写容纳面、镜像档 × 车道)收成导出函数,
+ * 装配器与受理门同调;规则表的那一判与存量体重放预判共用一只组合(`http/stored-body-replay.ts` 的 `ruleTablesRefusalWithoutTaskRoot`)。
+ */
+import type { IncomingMessage } from "node:http";
+import { type TaskHostPostureScope, type TaskWriteFaceInput } from "./hosted-posture.js";
+import { type ToolListSide } from "./rule-entry-list.js";
+import { type Scenario } from "./owner-brands.js";
+import type { PermissionMode } from "@sema-agent/core";
+import type { ServiceConfig } from "./config-types.js";
+import type { TaskRequestBody } from "./http/wire-types.js";
+/**
+ * 一次提交请求的场景名从哪来(唯一读法):带场景头 ⇒ 头就是本请求的场景(分区与工具面同一个场景);体再给一个不同的 ⇒ 400 `scenario_conflict`
+ * (只在提交腿:读面没有体)。没带头 ⇒ 体原样(缺席 ⇒ 门走指派链)。
+ */
+export declare function scenarioRequestedBy(headerScenario: Scenario | undefined, bodyScenario: unknown): unknown;
+/**
+ * `inheritEnv:"all"` 的车道与射程两判(值形判在 `request-value-closure.ts` 的 `inheritEnvFieldIssue`,先于本函数):只有 host 车道消费这一位 ⇒ 别的车道 400 + 机读位
+ * `reason: lane_not_host`;射程读写容纳面那一只谓词(`hosted-posture.ts` 腿④)⇒ 托管 422 `request.host_posture_refused`。`"scrub"` 是缺省,任何车道受理。
+ */
+export declare function assertInheritEnvServed(body: {
+    readonly inheritEnv?: unknown;
+}, config: TaskHostPostureScope): void;
+/** 工具名清单里读成空的条目 ⇒ 400(判与句的属主 = `rule-entry-list.ts` `inertToolListEntryOf`;`sides` 缺省 = 两个方向都判,续跑腿只判限制方向)。 */
+export declare function assertToolListsReadable(body: unknown, sides?: readonly ToolListSide[]): void;
+/** 体 `attachmentIds` 的形:在场就必须是至多 16 只、每只 1–64 字符的串(只判形;句柄在不在、绑不绑得上读附件店,在装配器的绑定核)。 */
+export declare function assertAttachmentIdsShape(raw: unknown): void;
+/** 任务层「掀开写围栏」的模式词 × 部署天花板(判据与拒因属主 `hosted-posture.ts`)⇒ 422 `request.host_posture_refused`。 */
+export declare function assertWriteFaceAdmitted(mode: PermissionMode | undefined, config: TaskWriteFaceInput): void;
+/**
+ * 体点名的每任务镜像档 × 本部署的执行车道:车道不是 k8s ⇒ 501 `capability.k8s_lane_required`(这台部署接不了每任务镜像,换部署形态才行)。
+ * 装配器判的是**生效**的那一档(体给的 ∨ 会话绑定的);体给了档时会话绑定不读 ⇒ 这一判只读请求与车道,受理门在铸点之前判体那一档。
+ */
+export declare function assertImageProfileLane(profile: string | undefined, config: TaskHostPostureScope): void;
+/** 体上的每任务镜像档(非空串;形在受理门的值形门判过 —— 与装配器同一读法)。 */
+export declare function bodyImageProfileOf(body: {
+    readonly sandboxImageProfile?: unknown;
+}): string | undefined;
+/**
+ * **新提交的请求形判,铸点之前一次答完**(受理漏斗在值形门之后、授权器之前调;抛 `HttpError`,与装配器的同名判同句同码)。
+ * `body` = 受理门盖过入口模式章的那一份(装配器拿到的就是它)。序 = 装配器里这些判的序(一份体同时撞上两只时,先答的与修前同一只):
+ * 主体(场景头的三判)→ MCP 条目 → `inheritEnv` 车道 / 射程 → 工具名清单 → A2A 条目(超 32 条整份拒)→ `images` → 场景头 × 体 → `attachmentIds` 形 → 写容纳面 →
+ * 规则表里不靠任务根的拒(三桶 → `neverAuto`)→ 体点名的镜像档 × 车道。
+ * 不在这里的:装配器自己装配的事实(运维锁集、数据根、店的接线)、热应用的模型面(目录 / 名单 / 拒因表)、会话 / 店 / 中心 / 在飞 / 引擎 —— 那些判在铸点之后,拒走条件撤回。
+ */
+export declare function assertRequestFormBeforeMint(body: TaskRequestBody, req: IncomingMessage, config: ServiceConfig): void;
+//# sourceMappingURL=request-form.d.ts.map