@sema-agent/server 7.147.0 → 7.149.0

package/dist/fleet-client.js

@@ -4,6 +4,7 @@ import { centerFetch, centerLaneConfigured } from "./web-admin-client/center-req
 import { recordFailOpen } from "./observability/fail-open.js";
 import { createIdentityBins, pinAccountingIdentity } from "./center-credential.js";
 import { WEB_ADMIN_ENV } from "@sema-agent/settings-schema";
+import { readUpstreamJson } from "./upstream-body.js";
 export const FLEET_USAGE_KEY_CAP = 1024;
 export const FLEET_CLIENT_FETCH_TIMEOUT_MS = 5000;
 export class FleetUsageAccumulator {
@@ -94,7 +95,7 @@ async function rejectionSnippet(res) {
 async function capabilityReadingOf(res) {
     let body;
     try {
-        body = await res.json();
+        body = await readUpstreamJson(res);
     }
     catch (err) {
         return { kind: "unreadable", why: "body", detail: err instanceof Error ? err.message : String(err) };
@@ -102,10 +103,9 @@ async function capabilityReadingOf(res) {
     return readCapabilityReading(body);
 }
 export function startFleetClient(opts) {
-    const f = opts.fetchImpl ?? fetch;
     const heartbeatMs = opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
     const usageWindowMs = opts.usageWindowMs ?? 60_000;
-    const send = (route, method, json, center = opts.center) => centerFetch(center, { kind: route }, { method, json, timeoutMs: FLEET_CLIENT_FETCH_TIMEOUT_MS, fetchImpl: f });
+    const send = (route, method, json, center = opts.center) => centerFetch(center, { kind: route }, { method, json, timeoutMs: FLEET_CLIENT_FETCH_TIMEOUT_MS, fetchImpl: opts.fetchImpl });
     let stopped = false;
     let failStreak = 0;
     let unreadableStreak = 0;

package/dist/fleet-lease.d.ts

@@ -89,7 +89,6 @@ export declare class FleetLeaseManager {
     private readonly opts;
     /** 记账身份的那一箱(惰建;分箱规则只有 `createIdentityBins` 一只,取箱口 `accounting`)。 */
     private readonly binNow;
-    private readonly f;
     private readonly now;
     private failStreak;
     /** [ref] ②:最近一次谈判的收尾({@link LeaseAdmitOutcome})。只在 `issueOrRenewInner` 的各收尾点写。 */

package/dist/fleet-lease.js

@@ -1,6 +1,7 @@
 import { QuotaLease, leaseExhausted, shouldRenewLease } from "@sema-agent/settings-schema/fleet";
 import { CenterCredentialUnavailableError, createIdentityBins, pinAccountingIdentity } from "./center-credential.js";
 import { centerFetch, centerLaneConfigured } from "./web-admin-client/center-request.js";
+import { readUpstreamJson } from "./upstream-body.js";
 export const NOT_LEASE_TTL_MS = 10 * 60 * 1000;
 export const EXHAUSTED_RETRY_MS = 30 * 1000;
 export const LEASE_PRINCIPAL_CAP = 4096;
@@ -24,14 +25,12 @@ const LEASE_HEALTH_BY_OUTCOME = {
 export class FleetLeaseManager {
     opts;
     binNow;
-    f;
     now;
     failStreak = 0;
     lastAdmit = "none";
     failMode;
     constructor(opts) {
         this.opts = opts;
-        this.f = opts.fetchImpl ?? fetch;
         this.now = opts.now ?? Date.now;
         this.failMode = opts.failMode;
         this.binNow = createIdentityBins(opts.center.credential, (pinned) => ({
@@ -127,10 +126,10 @@ export class FleetLeaseManager {
                 method: "POST",
                 json: { principal, worker: this.opts.center.worker },
                 timeoutMs: LEASE_FETCH_TIMEOUT_MS,
-                fetchImpl: this.f,
+                fetchImpl: this.opts.fetchImpl,
             });
             if (res.status === 200) {
-                const body = (await res.json());
+                const body = (await readUpstreamJson(res));
                 const lease = QuotaLease.parse(body.lease);
                 this.set(bin, principal, { kind: "lease", lease });
                 if (this.failStreak > 0)
@@ -142,7 +141,7 @@ export class FleetLeaseManager {
             }
             if (res.status === 409) {
                 this.lastAdmit = "ok";
-                const body = (await res.json().catch(() => ({})));
+                const body = (await readUpstreamJson(res).catch(() => ({})));
                 if (body.code === "quota_exhausted") {
                     const until = this.now() + EXHAUSTED_RETRY_MS;
                     const detail = {

package/dist/history-anchor.d.ts

@@ -1,4 +1,22 @@
+import { readVisibleRun, type Entry, type OwnerAccessWiring } from "./http/owner-access.js";
+import type { Caller } from "./owner-faces.js";
 import type { ResumeAnchorStore } from "./plugins/store-backend.js";
+import type { IncomingMessage } from "node:http";
+/**
+ * 手柄翻译读的两只店(一个值,两位读者:提交面阶段③ 与 run 外回退口同递):
+ *  · `anchors` —— 手柄 → entry id 的唯一一张表;
+ *  · `runs` —— 只在手柄**未知**时经属主存取器读一次 run 行(`readVisibleRun`,型取自它的 run 店形参),只为 404 选成因半句。
+ */
+export interface HistoryAnchorReaders {
+    readonly anchors: Pick<ResumeAnchorStore, "resolve">;
+    readonly runs: Parameters<typeof readVisibleRun>[1];
+}
+/**
+ * 成因半句的读者(唯一铸法;提交面阶段③、run 外回退口与钉同铸):口 = 面表 `run.anchor` —— 属主 / 无主,不放运维、不放 fleet,登 raw(这一读只为选句、
+ * 不答 run 的状态 ⇒ 不过观察口,不替任何一条行落判决)。调用方由调用点按自己的身份读法铸好交来:提交面 = 提交挂接的 `claimCallerOf`(该面不放运维 / fleet,
+ * 两格恒缺不漏判),run 外口 = 请求调用方(运维代人回退时这半句不点名那位属主的提问 —— 只少一句说明,不说不成立的话)。
+ */
+export declare function anchorReaderOf(req: IncomingMessage, w: OwnerAccessWiring, caller: Caller): Entry;
 /** 两族:码与句尾(出路)。键 = 族名;加一族 = 加一行(两只调用方按族名取,不手写码)。 */
 declare const HISTORY_ANCHOR_FAMILIES: {
     /** 分叉式回卷(会话在那条消息处分叉)。 */
@@ -14,9 +32,11 @@ declare const HISTORY_ANCHOR_FAMILIES: {
 };
 export type HistoryAnchorFamily = keyof typeof HISTORY_ANCHOR_FAMILIES;
 /**
- * 手柄 → entry id;未知 ⇒ 抛 404(族码 + 共用半句)。`owner` = 锚行的属主键(锚店的 null-safe 属主守卫):提交面传提交者,run 外口传会话属主
- * (门已证调用方读得到这只会话;锚由这只会话的提交落下,属主键就是会话属主 —— 运维代人回退读的是同一把键)。`field` = 句首点名的请求字段。
+ * 手柄 → entry id;未知 ⇒ 抛 404(族码 + 成因半句 + 族的出路)。`owner` = 锚行的属主键(锚店的 null-safe 属主守卫):提交面传提交者,run 外口传会话属主
+ * (门已证调用方读得到这只会话;锚由这只会话的提交落下,属主键就是会话属主 —— 运维代人回退读的是同一把键)。`reader` = 收到这句 404 的那位调用方的存取器入口
+ * (只给成因半句的 run 行读用,见 {@link unknownAnchorCause}),由 {@link anchorReaderOf} 铸。
+ * `field` = 句首点名的请求字段。
  */
-export declare function resolveHistoryAnchor(family: HistoryAnchorFamily, store: Pick<ResumeAnchorStore, "resolve">, sessionId: string, handle: string, owner: string | null, field: string): Promise<string>;
+export declare function resolveHistoryAnchor(family: HistoryAnchorFamily, readers: HistoryAnchorReaders, reader: Entry | undefined, sessionId: string, handle: string, owner: string | null, field: string): Promise<string>;
 export {};
 //# sourceMappingURL=history-anchor.d.ts.map

package/dist/history-anchor.js

@@ -1,14 +1,34 @@
 import { HttpError } from "./security.js";
-const NO_ANCHOR_HINT = "no rewind anchor is recorded under that handle (a prompt that carried attachments records none when its attachment frames were interrupted or their count did not match)";
+import { recordFailOpen } from "./observability/fail-open.js";
+import { protocolEntry, readVisibleRun } from "./http/owner-access.js";
+const NO_ANCHOR = "no rewind anchor is recorded under that handle";
+const PROMPT_WITHOUT_ANCHOR = `${NO_ANCHOR}: it names a prompt of this session that recorded none (a prompt that carried attachments records none when its attachment frames were interrupted or their count did not match)`;
+export function anchorReaderOf(req, w, caller) {
+    return protocolEntry(req, w, "run.anchor", caller);
+}
+async function unknownAnchorCause(readers, reader, sessionId, handle) {
+    if (reader === undefined)
+        return NO_ANCHOR;
+    try {
+        const run = await readVisibleRun(reader, readers.runs, handle);
+        if (run === undefined || run.sessionId !== sessionId)
+            return NO_ANCHOR;
+        return (await readers.anchors.resolve(sessionId, handle, run.owner)) === undefined ? PROMPT_WITHOUT_ANCHOR : NO_ANCHOR;
+    }
+    catch (err) {
+        recordFailOpen("server.resume-anchor.cause-read-failed", `error=${err instanceof Error ? err.name : typeof err}`);
+        return NO_ANCHOR;
+    }
+}
 const HISTORY_ANCHOR_FAMILIES = {
     resumeAt: { code: "resume_at.unknown_event", wayOut: "give an explicit resumeAt" },
     rewindFilesTo: { code: "rewind_files_to.unknown_event", wayOut: "name another prompt" },
 };
-export async function resolveHistoryAnchor(family, store, sessionId, handle, owner, field) {
-    const entryId = await store.resolve(sessionId, handle, owner);
+export async function resolveHistoryAnchor(family, readers, reader, sessionId, handle, owner, field) {
+    const entryId = await readers.anchors.resolve(sessionId, handle, owner);
     if (entryId !== undefined)
         return entryId;
     const { code, wayOut } = HISTORY_ANCHOR_FAMILIES[family];
-    throw new HttpError(404, `${field}: no such message in this session (${code}) — ${NO_ANCHOR_HINT}; ${wayOut}`, { code });
+    throw new HttpError(404, `${field}: no such message in this session (${code}) — ${await unknownAnchorCause(readers, reader, sessionId, handle)}; ${wayOut}`, { code });
 }
 //# sourceMappingURL=history-anchor.js.map

package/dist/hitl-delivery.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 人在环帧(问题 / 表单 / 审批三族)的**投递律** —— 全仓唯一属主。
+ *
+ * 一条律:经腿的协调器上下文投出的人在环帧(开帧、收帧、撤卡帧),在有账本的腿上**先落本 run 账本、再写直写面**;账本落不下 ⇒
+ * 这一帧不上直写面。一只帧「送到」= 账本在这一次投递的 sink 集里 ⇒ 看账本那一笔;否则看直写那一笔。三族、三条腿共用:
+ *  · {@link createHitlTransport} —— 一条腿**一只**传输(无状态;不记谁接下过什么);
+ *  · {@link createHitlOpenRace} —— 一只开帧的竞速机:开帧投递(可以是多个目标)与该族的结算谁先;收帧只投给接下过开帧的 sink、
+ *    排在该目标的开帧之后(**配对只此一处**);
+ *  · {@link deliverHitlNotice} —— 无配对的通知帧(批级撤卡)。
+ *
+ * 族只写自己的挂点(投前判、送到 / 没送到 / 悬着之后的记账与结算词);律与配对不在族里。
+ *
+ * 「先账本后直写」与 sync 腿引擎帧同一形(引擎帧先 `await ledgerSink.onEvent(ev)` 再直写),只是更软:人在环帧落不下只让这一次
+ * 投递失败,不让腿死。连接级对账帧(开流 preamble 与它的订阅消卡帧)不经腿的上下文、不进账本,不在本律射程。
+ */
+import type { QuestionFrame } from "./question.js";
+import type { ElicitationFrame } from "./elicitation.js";
+import type { ApprovalCardLegFrame, ApprovalRevokeFrame } from "./approval-card.js";
+import type { ToolApprovalFrame } from "./tool-approval.js";
+import type { LedgerEventType } from "./trace/ledger-events.js";
+/** 三族的人在环帧(开 / 收 / 撤)。九个帧型全在账本闭集里(下面那条编译期断言)。 */
+export type HitlFrame = QuestionFrame | ElicitationFrame | ApprovalCardLegFrame | ApprovalRevokeFrame | ToolApprovalFrame;
+/**
+ * 一次投递在各只 sink 上的接下与否 —— **只有这一次投递涉及的 sink 才有键**(不在场 / 不在 `onto` 里的没有键)。
+ * 也是 {@link HitlTransport.deliver} 的 `onto` 入参形:值为 `true` 的 sink 才写。
+ */
+export interface HitlSinks {
+    readonly ledger?: boolean;
+    readonly live?: boolean;
+}
+/**
+ * 一条腿的传输(无状态)。`deliver` 与 `reachable` 是**属性**(不是方法签名)—— 帧型参数因此逆变。腿上装出的那一只是全族型(`HitlTransport<HitlFrame>`,
+ * 一腿一只、三族共用);**窄化发生在装进族上下文那一步**:审批上下文的判别联合把传输型钉到本族帧(呈卡族收不进旧族帧),竞速机的目标从族上下文取
+ * ⇒ 混族的 (transport, frame) 对编译不过。直接拿全族型传输喂竞速机的代码不受这道型约束(三只协调器都从族上下文取,`P14` 编译期钉)。
+ */
+export interface HitlTransport<F extends HitlFrame> {
+    /**
+     * 投一帧:`onto` 缺省 = 在场的全部 sink。① 账本在 `onto` 里 ⇒ 先等账本;落不下 ⇒ 直写不写,返回。② 直写在 `onto` 里 ∧ 活着 ⇒ 写;
+     * 写抛 / 已死 ⇒ 直写没接下(不碰死连接)。③ 交回每只涉及的 sink 接下与否。**永不 reject。**
+     */
+    readonly deliver: (frame: F, onto?: HitlSinks) => Promise<HitlSinks>;
+    /** 判决面谓词:有直写 ⇒ 直写此刻活着;只有账本 ⇒ 恒真(账本 tail 随时可被接上)。谓词读不出 ⇒ 假(判决面 fail-closed 到停驻)。 */
+    readonly reachable: () => boolean;
+}
+/** 直写面:一个具名帧写 + 「此刻还活着吗」。 */
+export interface HitlLiveSink<F extends HitlFrame> {
+    readonly write: (frame: F) => void;
+    readonly alive: () => boolean;
+}
+/**
+ * 一条腿的传输。sink 组合闭集:`{ledger}`(后台 / 续跑腿)、`{ledger, live}`(sync 流腿有 durable run 行)、`{live}`(sync 流腿无 durable run 行);
+ * 两只都缺 = 装配错,构造即抛。账本 sink = 该腿账本的串行追加口(seq 由它那条链铸);直写 sink = 该连接的具名帧写。
+ */
+export declare function createHitlTransport<F extends HitlFrame = HitlFrame>(sinks: {
+    readonly ledger?: (type: LedgerEventType, data: unknown) => Promise<void>;
+    readonly live?: HitlLiveSink<F>;
+}): HitlTransport<F>;
+/** 开帧竞速的相:全部目标落定的聚合(任一送到 ⇒ `delivered`)先到,或该族的结算先到(`stalled`)。 */
+export type HitlPhase = "delivered" | "undelivered" | "stalled";
+/** 一只开帧的竞速机(一次登记一只)。 */
+export interface HitlOpenRace<F extends HitlFrame> {
+    /** 「全部目标落定」的聚合与结算谁先。 */
+    readonly phase: Promise<HitlPhase>;
+    /** 全部目标落定后的聚合(`stalled` 之后迟到的那一判;零目标 ⇒ `undelivered`)。 */
+    readonly landing: Promise<"delivered" | "undelivered">;
+    /** 第 `target` 个目标的直写 sink 接下过开帧没有(preamble 订阅的让位判据)。 */
+    readonly acceptedLive: (target: number) => Promise<boolean>;
+    /**
+     * 收帧:逐目标逐 sink,只投接下过开帧的 sink、排在该目标的开帧之后;账本那只落不下 ⇒ 同目标直写不写。
+     * 一个目标的收帧没送到 ⇒ 记一次 `server.hitl.close-frame-dropped`。没接下过开帧的目标不收(不留孤儿收帧)。
+     */
+    readonly close: (frame: F) => void;
+}
+/**
+ * 开帧竞速机 —— 开帧投递与结算的竞速、迟到判与逐 sink 配对的唯一属主。
+ *
+ * 先登记后投(族在建它之前已把这一问登记好,快答不漏)。聚合等**全部**目标落定:任一送到 ⇒ `delivered`,全没送到 ⇒ `undelivered`
+ * (审批广播的「全部落定」语义;问题 / 表单单目标,任一 = 全部)。帧型与传输型同一个 `F`:传输型已窄到一族时(族上下文里取的那只),混族目标编译不过。
+ */
+export declare function createHitlOpenRace<F extends HitlFrame>(args: {
+    readonly targets: ReadonlyArray<{
+        readonly transport: HitlTransport<F>;
+        readonly frame: F;
+    }>;
+    /** 该族的结算(答 / 窗 / 中止 / 清扫 —— 永不 reject)。 */
+    readonly settled: Promise<unknown>;
+}): HitlOpenRace<F>;
+/** 无配对的通知帧(批级撤卡):同一只传输、同一条律;没送到 ⇒ 记一次 `server.hitl.close-frame-dropped`。永不 reject。 */
+export declare function deliverHitlNotice<F extends HitlFrame>(transport: HitlTransport<F>, frame: F): Promise<void>;
+//# sourceMappingURL=hitl-delivery.d.ts.map

package/dist/hitl-delivery.js

@@ -0,0 +1,98 @@
+import { recordFailOpen } from "./observability/fail-open.js";
+import { createLogger } from "./observability/logger.js";
+import { errorKindOf } from "./observability/err-text.js";
+const logger = createLogger();
+const _hitlTypesAreLedgerTypes = true;
+void _hitlTypesAreLedgerTypes;
+function landed(accepted) {
+    return accepted.ledger !== undefined ? accepted.ledger : accepted.live === true;
+}
+function frameKey(frame) {
+    switch (frame.type) {
+        case "question":
+        case "question_complete":
+            return `question=${frame.questionId}`;
+        case "elicitation":
+        case "elicitation_complete":
+            return `elicitation=${frame.elicitationId}`;
+        case "approval_request":
+        case "approval_complete":
+        case "tool_approval":
+        case "tool_approval_complete":
+            return `approval=${frame.approvalId}`;
+        case "approval_revoke":
+            return `batch=${frame.batchId}`;
+    }
+}
+function liveAlive(live) {
+    try {
+        return live.alive();
+    }
+    catch (err) {
+        logger.warn("hitl_live_alive_unreadable", { errKind: errorKindOf(err) });
+        return false;
+    }
+}
+export function createHitlTransport(sinks) {
+    const { ledger, live } = sinks;
+    if (ledger === undefined && live === undefined)
+        throw new Error("createHitlTransport: a leg's HITL transport needs a ledger sink, a live sink, or both");
+    const noteFailed = (frame, sink, err) => logger.warn("hitl_sink_write_failed", { frame: frame.type, key: frameKey(frame), sink, errKind: errorKindOf(err) });
+    const deliver = async (frame, onto) => {
+        const liveSink = live !== undefined && (onto === undefined || onto.live === true) ? live : undefined;
+        let ledgerAccepted;
+        if (ledger !== undefined && (onto === undefined || onto.ledger === true)) {
+            const { type, ...data } = frame;
+            try {
+                await ledger(type, data);
+                ledgerAccepted = true;
+            }
+            catch (err) {
+                noteFailed(frame, "ledger", err);
+                return liveSink !== undefined ? { ledger: false, live: false } : { ledger: false };
+            }
+        }
+        if (liveSink === undefined)
+            return ledgerAccepted !== undefined ? { ledger: ledgerAccepted } : {};
+        let liveAccepted = false;
+        if (liveAlive(liveSink)) {
+            try {
+                liveSink.write(frame);
+                liveAccepted = true;
+            }
+            catch (err) {
+                noteFailed(frame, "live", err);
+            }
+        }
+        return ledgerAccepted !== undefined ? { ledger: ledgerAccepted, live: liveAccepted } : { live: liveAccepted };
+    };
+    return { deliver, reachable: () => live === undefined || liveAlive(live) };
+}
+export function createHitlOpenRace(args) {
+    const opens = args.targets.map((t) => t.transport.deliver(t.frame));
+    const landing = Promise.all(opens).then((all) => (all.some(landed) ? "delivered" : "undelivered"));
+    const phase = Promise.race([landing, args.settled.then(() => "stalled")]);
+    const acceptedLive = (target) => {
+        const open = opens[target];
+        if (open === undefined)
+            throw new RangeError(`createHitlOpenRace: no target #${target}`);
+        return open.then((a) => a.live === true);
+    };
+    const close = (frame) => {
+        args.targets.forEach((t, i) => {
+            void opens[i].then(async (opened) => {
+                const onto = { ...(opened.ledger === true ? { ledger: true } : {}), ...(opened.live === true ? { live: true } : {}) };
+                if (onto.ledger !== true && onto.live !== true)
+                    return;
+                if (!landed(await t.transport.deliver(frame, onto)))
+                    recordFailOpen("server.hitl.close-frame-dropped", `frame=${frame.type} ${frameKey(frame)}`);
+            });
+        });
+    };
+    return { phase, landing, acceptedLive, close };
+}
+export async function deliverHitlNotice(transport, frame) {
+    if (!landed(await transport.deliver(frame)))
+        recordFailOpen("server.hitl.close-frame-dropped", `frame=${frame.type} ${frameKey(frame)}`);
+}
+//# sourceMappingURL=hitl-delivery.js.map

package/dist/hooks/classic-stations.d.ts

@@ -4,14 +4,15 @@
  * 三件事只写在这里:
  *  ① **事件名 → { `e` 型, 答案型 }**:读 core 的 `ClassicEventMap`(7.56.0 起包根导出;此前本文件手写十一行配对,随之删)。
  *     每站的角色(链 / 观察)由 {@link CLASSIC_STATION_ROLE} 说,它在编译期对着 core 的答案形核:答案形是 `ObservedAnswer` 的站必须是 `observe`、其余是 `chain`。
- *  ② **handler 怎么挂**:链成员「无意见 ⇒ `next(e)`」(链 handler 返回 `undefined` 是站点违约,refuse 站上即 fail-closed 拒),
+ *  ② **handler 怎么挂**:链成员「体无话 ⇒ 下方的答案原样作数」(链 handler 返回 `undefined` 是站点违约,refuse 站上即 fail-closed 拒),
  *     观察者「恒返回 `undefined`」(观察者的判词不采纳、被引擎报告)。两条都在 {@link hangClassic} / {@link observeClassic} 里成形,
  *     调用方只写「这一站我答什么」或「这一站我看什么」,不再各自记得这两条。
  *  ③ **停表**:引擎交给每只 handler 的 `next.signal` 是「这只 handler 的预算 ∪ 这次派发结束 / 被取消」的合成(core 的派发器自合成,本仓不另合成第二份);
  *     成因只读引擎的读数 `next.budget.remainingMs`(用尽 = 0),不解析信号的文案。两样一起是 handler 体的第二个入参 {@link HandlerHalt} ——
  *     触发之后 handler 不再起新事、在飞的子进程要叫停(`hooks/hook-runner.ts` 的命令钩子腿);是自己的预算用尽,托管车道把撞上的条目记成未跑成。
- *  ④ **两种链上挂法**:内层「先答,无意见再 `next(e)`」({@link hangClassic});外层「先 `next(e)`,在答回来的答案上再答」({@link wrapClassic})——
- *     外层 handler 等 `next` 的那段引擎停它的表(core `SelfBudget` 的暂停),所以外层的预算只算它自己的时间。
+ *  ④ **链上只有一种挂法:折叠**({@link hangClassic})——「先 `next(e)`,在答回来的答案上再答」:本仓铸的每张注册都判下方全部改写之后的那一份,
+ *     下方的否决恒是最后一票(上方体答 `undefined` ⇒ 原样作数),上方的放行跳不过下方的守卫。等 `next` 的那段引擎停这只 handler 的表(core `SelfBudget` 的暂停),
+ *     所以每只的预算只算它自己的时间。「先答,无意见再 `next(e)`」的内层形已退役 —— 两种挂法并存时,一张注册的放行能跳过链下方另一张的守卫。
  *
  * 站的集合 = 引擎事件表里有站的 `classic.*` 名(一条钉从 `MOD_EVENT_TABLE` 派生对拍,不手抄第二份)。
  * 观察站(`StopFailure` / `PostCompact` / `PermissionDenied` / `SessionStart` / `SessionEnd`)只许观察者:答案形是「无」,core 的迁移配方要求挂 `{ observe: true }`。
@@ -48,20 +49,16 @@ export interface HandlerHalt {
 }
 /**
  * 一站的 handler 体:读 `e`,答这一站的答案;`undefined` = 无意见。`halt` 见 {@link HandlerHalt}。
- * `below` = 外层挂法下(见 {@link wrapClassic})链下方答回来的那份答案(接收后冻结的数据;下方都无意见时是引擎核心的空答案)—— 内层挂法与观察站恒 `undefined`。
- * 外层体答 `undefined` = 下方的答案原样作数;要换掉它就交一份新答案(把下方的成员并进去是体自己的事)。
+ * `below` = 链站上链下方答回来的那份答案(见 {@link hangClassic};接收后冻结的数据;下方都无意见时是引擎核心的空答案)—— 观察站恒 `undefined`。
+ * 体答 `undefined` = 下方的答案原样作数;要换掉它就交一份新答案(把下方的成员并进去是体自己的事)。
  */
 export type ClassicAnswer<K extends ClassicStation> = (e: ClassicEventMap[K]["e"], halt: HandlerHalt, below: unknown) => Promise<StationAnswer<K> | undefined>;
 /**
- * 内层挂法:链站 ⇒ 链成员 `(await answer(e)) ?? next(e)`;观察站 ⇒ 观察者(体照跑、恒返回 `undefined`)。
+ * 链上唯一的挂法(折叠,头注 ④):链站 ⇒ 先 `next(e)`(下方的链成员与引擎核心先跑完,这一只的表在等的那段停着),再拿答回来的答案作答 —— 体答 `undefined` ⇒ 下方的答案原样作数;
+ * 下方在拒站上失败 ⇒ 派发已 fail-closed 终局,`next` 抛,体不跑。观察站 ⇒ 观察者(体照跑、恒返回 `undefined`;观察者不进链,没有「下方」)。
  * `e` 的型由 core 的 `ClassicEventMap` 给(引擎交来的是本站的 `e`;见头注 ①)。
  */
 export declare function hangClassic<K extends ClassicStation>(on: On<EngineDollar>, station: K, answer: ClassicAnswer<K>): void;
-/**
- * 外层挂法:链站 ⇒ 先 `next(e)`(下方的链成员与引擎核心先跑完,这一只的表在等的那段停着),再拿答回来的答案作答 —— 体答 `undefined` ⇒ 下方的答案原样作数;
- * 下方在拒站上失败 ⇒ 派发已 fail-closed 终局,`next` 抛,体不跑。观察站 ⇒ 与 {@link hangClassic} 同(观察者不进链,没有「下方」)。
- */
-export declare function wrapClassic<K extends ClassicStation>(on: On<EngineDollar>, station: K, answer: ClassicAnswer<K>): void;
 /** 挂一只观察者(任何站都可):拿分离副本、不进链、恒返回 `undefined`;`halt` 同 {@link ClassicAnswer}。 */
 export declare function observeClassic<K extends ClassicStation>(on: On<EngineDollar>, station: K, watch: (e: ClassicEventMap[K]["e"], halt: HandlerHalt) => void | Promise<void>): void;
 export {};

package/dist/hooks/classic-stations.js

@@ -35,13 +35,6 @@ export function hangClassic(on, station, answer) {
         observeClassic(on, station, async (e, halt) => void (await answer(e, halt, undefined)));
         return;
     }
-    on(station, async (_$, e, next) => (await withHalt(next, (halt) => answer(e, halt, undefined))) ?? next(e));
-}
-export function wrapClassic(on, station, answer) {
-    if (CLASSIC_STATION_ROLE[station] === "observe") {
-        hangClassic(on, station, answer);
-        return;
-    }
     on(station, async (_$, e, next) => {
         const below = await next(e);
         return (await withHalt(next, (halt) => answer(e, halt, below))) ?? below;

package/dist/hooks/command-spawn.d.ts

@@ -46,9 +46,14 @@ export type CommandSpawnPlan = {
 export declare function composeHookEnvLayer(requestEnv: Readonly<Record<string, string>> | undefined, cwd: string, plugin: HookPluginContext | undefined): Record<string, string> & {
     CLAUDE_PROJECT_DIR: string;
 };
+/**
+ * 这条 hook 的子进程会拿到的环境:有效环境层叠在继承那一半之上(组合属主 = `hook-runner.ts` 的 `hookChildEnv`,本模块不写第二份组合,只问它的读数)。
+ * 组合拒(授予形坏 / 放回点到本服务自有凭据名)⇒ 抛,起法按「起不来」答(与 spawn 时组合抛同一个结局)。
+ */
+export type HookChildEnvOf = (layer: Readonly<Record<string, string>>) => Readonly<Record<string, string | undefined>>;
 /**
  * 一条 command 条目的起法(规则见文件头)。`cwd` = 本次 hook 的工作目录(`CLAUDE_PROJECT_DIR` 的缺省值);`requestEnv` = 请求 `settings.env`(hook 环境的一层;**必传**:没有就显式传 `undefined`,
- * 漏传是编译红,不会静默丢掉请求给的 env),合并与读法见 {@link composeHookEnvLayer} / {@link contextVarValue}。有副作用的只有两步,都只在条目带 `plugin` 时发生:读插件根是否是目录、建数据目录(CC 同:注入即建)。
+ * 漏传是编译红,不会静默丢掉请求给的 env),合并与读法见 {@link composeHookEnvLayer} / {@link contextVarValue};`childEnvOf` = 组合的读数入口({@link HookChildEnvOf})。有副作用的只有两步,都只在条目带 `plugin` 时发生:读插件根是否是目录、建数据目录(CC 同:注入即建)。
  */
-export declare function planCommandSpawn(entry: RunnableCommandHookEntry, cwd: string, requestEnv: Readonly<Record<string, string>> | undefined): Promise<CommandSpawnPlan>;
+export declare function planCommandSpawn(entry: RunnableCommandHookEntry, cwd: string, requestEnv: Readonly<Record<string, string>> | undefined, childEnvOf: HookChildEnvOf): Promise<CommandSpawnPlan>;
 //# sourceMappingURL=command-spawn.d.ts.map

package/dist/hooks/command-spawn.js

@@ -59,17 +59,24 @@ const refOf = (name) => "${" + name + "}";
 export function composeHookEnvLayer(requestEnv, cwd, plugin) {
     return { ...requestEnv, CLAUDE_PROJECT_DIR: requestEnv?.CLAUDE_PROJECT_DIR ?? cwd, ...hookPluginEnv(plugin) };
 }
-function contextVarValue(name, layer) {
-    const v = layer[name];
+function contextVarValue(name, env) {
+    const v = env[name];
     return v !== undefined && v.length > 0 ? v : undefined;
 }
-export async function planCommandSpawn(entry, cwd, requestEnv) {
+export async function planCommandSpawn(entry, cwd, requestEnv, childEnvOf) {
     const texts = [entry.command, ...(entry.args ?? [])];
     const p = entry.plugin;
     const env = composeHookEnvLayer(requestEnv, cwd, p);
+    let seen;
+    try {
+        seen = childEnvOf(env);
+    }
+    catch (e) {
+        return { kind: "refused", error: e instanceof Error ? e.message : String(e) };
+    }
     const values = new Map([["CLAUDE_PROJECT_DIR", env.CLAUDE_PROJECT_DIR]]);
     for (const [name, ref] of CONTEXT_VARS) {
-        const value = contextVarValue(name, env);
+        const value = contextVarValue(name, seen);
         if (value !== undefined) {
             values.set(name, value);
             continue;
@@ -79,8 +86,8 @@ export async function planCommandSpawn(entry, cwd, requestEnv) {
         return {
             kind: "refused",
             error: p !== undefined
-                ? `hook command references ${ref} but only ${ROOT_REF} is available for this hook (it carries no plugin data directory and the request settings.env does not set ${name})`
-                : `hook command references ${ref} but the hook is not associated with a plugin and the request settings.env does not set ${name} (the variable is only available to hooks that carry a plugin context, or to a request that sets it in settings.env)`,
+                ? `hook command references ${ref} but only ${ROOT_REF} is available for this hook (it carries no plugin data directory and the hook environment does not set ${name}; a request can set it in settings.env)`
+                : `hook command references ${ref} but the hook is not associated with a plugin and the hook environment does not set ${name} (the variable is set for hooks that carry a plugin context; a request can set it in settings.env)`,
         };
     }
     if (p !== undefined) {

package/dist/hooks/hook-llm.d.ts

@@ -1,3 +1,4 @@
+import { type Model } from "@sema-agent/core";
 import type { ModelKeyRef } from "../key-resolver.js";
 import type { ServiceConfig } from "../config-types.js";
 import type { HookLlmCall, HookLlmFailureCode } from "./hook-runner.js";
@@ -24,12 +25,15 @@ import type { HookLlmCall, HookLlmFailureCode } from "./hook-runner.js";
  * ([ref] 的 (a) 路已兑现:core 7.53.0 [ref] 根导出了那只判官 `brainLaneOf(model, routes)` —— `createRoutingBrain` 对每个请求问的就是它;
  * 本仓自写的合取 `dispatchBrainLane` 随之退役,本调用点与另三处一并改问它。)
  */
-export type HookModelPick = {
+export type HookModelPick = 
+/** `model` = 选中的**条目本身**(名字 / 地址之外的第三样东西:推理席位的方言读它的 `reasoning` / `compat` / `thinkingLevelMap`;`catalogRef` 只是它的名)。 */
+{
     ok: true;
     catalogRef: string;
     providerModelId: string;
     baseUrl: string;
     api: "openai-completions" | "anthropic-messages";
+    model: Model;
 }
 /** 选不出来的那一臂自带失败码([ref]):两个载体(prompt 直连 / agent 子代理)共用这一只选模闸,同一只判词同一个码。 */
  | {

package/dist/hooks/hook-llm.js

@@ -1,11 +1,12 @@
-import { admitRouteRequest, BrainError, joinRequestUrl, resolveRouteCredential, routeKeyOf } from "@sema-agent/core";
+import { admitRouteRequest, applyReasoningToRequest, AUTO_MODE_CLASSIFIER_LOW_REASONING_BUDGET_TOKENS, BrainError, joinRequestUrl, lowestReasoningSeat, mergeReasoningHeaders, resolveRouteCredential, routeKeyOf } from "@sema-agent/core";
 import { matchCatalogModel, refusedCatalogEntry, servedModelTableLeg } from "../model-select.js";
 import { echoModelRef, modelUnavailableMessage } from "../model-entry-refusal.js";
 import { resolveOpenaiRouteEndpoint } from "../model-route-endpoint.js";
 import { anthropicLaneCredentialOf } from "../model-route-gap.js";
 import { anthropicRouteRoot, brainLaneFor, routeTableOf } from "../model-provider.js";
-import { egressRedirectRefusal } from "../egress-redirect.js";
+import { EgressRedirectRefusedError, createEgressFetch } from "../egress-redirect.js";
 import { buildDisplaySafeRefusal, redactSecrets } from "../trace/redact.js";
+import { readUpstreamJson } from "../upstream-body.js";
 const unresolvedPick = (error) => ({ ok: false, error, code: "model_unresolved" });
 export function buildHookFailureText(raw) {
     if (raw === "")
@@ -52,10 +53,10 @@ export function createHookLlm(deps) {
         const lane = brainLaneFor(m.provider, routeTableOf(config));
         switch (lane) {
             case "anthropic":
-                return { ok: true, catalogRef, providerModelId, baseUrl: m.baseUrl || anthropicRouteBaseUrl(), api: "anthropic-messages" };
+                return { ok: true, catalogRef, providerModelId, baseUrl: m.baseUrl || anthropicRouteBaseUrl(), api: "anthropic-messages", model: m };
             case "gateway": {
                 const endpoint = resolveOpenaiRouteEndpoint(catalogRef, m, config.gatewayBaseUrl, servedModelTableLeg(config));
-                return endpoint.ok ? { ok: true, catalogRef, providerModelId, baseUrl: endpoint.baseUrl, api: "openai-completions" } : unresolvedPick(endpoint.refusal);
+                return endpoint.ok ? { ok: true, catalogRef, providerModelId, baseUrl: endpoint.baseUrl, api: "openai-completions", model: m } : unresolvedPick(endpoint.refusal);
             }
         }
     };
@@ -108,8 +109,8 @@ export function createHookLlm(deps) {
         }
         return { ok: true, credential, admission };
     };
-    const fetchImpl = deps.fetchImpl ?? fetch;
-    const callLlm = async ({ prompt, model, timeoutMs, system, maxOutputTokens }) => {
+    const fetchImpl = createEgressFetch("declare the final endpoint as this route's base URL", deps.fetchImpl);
+    const callLlm = async ({ prompt, model, timeoutMs, system, maxOutputTokens, reasoningSeat }) => {
         const pick = hookModelFor(model);
         if (!pick.ok)
             return pick;
@@ -127,9 +128,12 @@ export function createHookLlm(deps) {
                     return { ok: false, error: `per-model key resolution for "${pick.catalogRef}" failed — refusing to fall back to the shared route credential (${String(e)})`, code: "credential_custody_failed" };
                 }
             }
+            const wireModel = { ...pick.model, api: pick.api };
+            const seat = reasoningSeat === "lowest" ? lowestReasoningSeat(wireModel) : undefined;
+            const thinkingRoom = seat === "low" ? AUTO_MODE_CLASSIFIER_LOW_REASONING_BUDGET_TOKENS : 0;
             let url;
             let headers;
-            let body;
+            let request;
             let admitted;
             let declaredRoot;
             if (pick.api === "anthropic-messages") {
@@ -146,9 +150,9 @@ export function createHookLlm(deps) {
                     "anthropic-version": config.anthropic?.version ?? "2023-06-01",
                     ...(routed.credential.source === "per-model" ? { "x-api-key": routed.credential.apiKey ?? "" } : routeCredentialHeader(routeCredential)),
                 };
-                const want = maxOutputTokens ?? 1024;
+                const want = (maxOutputTokens ?? 1024) + thinkingRoom;
                 const maxTokens = Math.min(config.models[pick.catalogRef]?.maxTokens ?? want, want);
-                body = JSON.stringify({ model: pick.providerModelId, max_tokens: maxTokens, ...(system ? { system } : {}), messages: [{ role: "user", content: prompt }] });
+                request = { model: pick.providerModelId, max_tokens: maxTokens, ...(system ? { system } : {}), messages: [{ role: "user", content: prompt }] };
             }
             else {
                 declaredRoot = config.gatewayBaseUrl;
@@ -159,8 +163,14 @@ export function createHookLlm(deps) {
                 const hookKey = routed.credential.apiKey;
                 url = joinRequestUrl(pick.baseUrl, "/chat/completions");
                 headers = { "content-type": "application/json", ...(hookKey ? { authorization: `Bearer ${hookKey}` } : {}) };
-                body = JSON.stringify({ model: pick.providerModelId, ...(maxOutputTokens !== undefined ? { max_tokens: maxOutputTokens } : {}), messages: [...(system ? [{ role: "system", content: system }] : []), { role: "user", content: prompt }], stream: false });
+                request = { model: pick.providerModelId, ...(maxOutputTokens !== undefined ? { max_tokens: maxOutputTokens + thinkingRoom } : {}), messages: [...(system ? [{ role: "system", content: system }] : []), { role: "user", content: prompt }], stream: false };
             }
+            if (seat !== undefined) {
+                const applied = applyReasoningToRequest({ api: pick.api, model: wireModel, level: seat, body: request });
+                request = applied.body;
+                mergeReasoningHeaders(headers, applied.headers);
+            }
+            const body = JSON.stringify(request);
             try {
                 admitted();
             }
@@ -168,15 +178,12 @@ export function createHookLlm(deps) {
                 return gateRefusal(pick, e, declaredRoot);
             }
             phase = "transport";
-            const r = await fetchImpl(url, { method: "POST", headers, body, signal: ac.signal, redirect: "manual" });
-            const redirected = egressRedirectRefusal(r, "declare the final endpoint as this route's base URL");
-            if (redirected !== undefined)
-                return { ok: false, error: `hook llm ${redirected}`, code: "redirect_refused" };
+            const r = await fetchImpl(url, { method: "POST", headers, body, signal: ac.signal });
             if (!r.ok)
                 return { ok: false, error: `hook llm HTTP ${r.status}`, code: "bad_response" };
             let answered;
             try {
-                answered = await r.json();
+                answered = await readUpstreamJson(r);
             }
             catch (e) {
                 if (ac.signal.aborted || e?.name !== "SyntaxError")
@@ -197,6 +204,8 @@ export function createHookLlm(deps) {
             return typeof text === "string" ? { ok: true, text } : { ok: false, error: "hook llm returned no content", code: "no_content" };
         }
         catch (e) {
+            if (e instanceof EgressRedirectRefusedError)
+                return { ok: false, error: `hook llm ${e.message}`, code: "redirect_refused" };
             const cause = e?.cause;
             return {
                 ok: false,