@sema-agent/server 7.146.0 → 7.148.0

package/dist/fleet/drain-entry.js

@@ -11,7 +11,7 @@ export const DRAIN_CAUSE_COUNTS_AS_FIRST_STOP_SIGNAL = {
     "self-exit:attachment": false,
 };
 export function blockingInflightOf(b) {
-    return b.http + b.leader;
+    return b.http + b.leader + b.backgroundAgents;
 }
 export function inflightTotal(b) {
     return blockingInflightOf(b) + b.sessionResident;

package/dist/fleet/fleet-bus.d.ts

@@ -47,6 +47,19 @@ export interface FleetTaskRow {
      *  改写成同一串;出生点校验过的字符集里也没有可脱敏的形。残余(已披露)= 有人把真凭据当队友名写进
      *  `Agent({name})`,那一串原样上 fleet 面。展示名 `name` 照旧脱敏。 */
     agentName?: string;
+    /** 这一行**跑在哪个模型上** —— core `BackgroundChildEvent.model`(spawn / tick 帧述它)**逐字**过境:引擎在 spawn 判定点解析出的
+     *  模型(per-call / agent 定义 / 继承;能解析到服务目录的就是服务那个目录 id)。它**不是**同一子代 `task_progress.model`
+     *  (那条腿自己 prepare 出的 id)—— 后者才是权威读数,本键是行级便利位:父 run 的活流结束后只剩 fleet 行的消费端,
+     *  从这里读得到,不必另存一份副本(一个事实一个源)。
+     *  🔴 **缺席是事实,不是缺口**:引擎没述(委派链上没有任何一处点名模型 ⇒ 子代跑 `subagent` 角色、具体 id 到它自己 prepare 才定;
+     *  留存账本的唤醒腿帧不带;老引擎)⇒ 键**不发** —— 不铸、不回落(不拿别处读到的值顶,空串也不补;**空串视同没述**)。
+     *  🔴 **一个事实一个源 = 帧本身 + 总线的 MERGE 底座**,发布方不私存副本:start 与 tick 帧述它;terminal 帧本身不述(core 7.66.0),
+     *  finish 行带的是总线上这一行**已有**的值 —— 与 `name` / `agentType` 同一个底座,所以行已离场之后才到的终态帧(陈述级退场后)是稀疏底座,
+     *  三者同缺席。复活(同 id 再 spawn)是新的一代:行已随终态离场,新一代的值只来自这一代引擎说过的话。前代迟到的 tick 被总线的判代闸
+     *  整帧丢掉,连同它带的 `model`。
+     *  未署名行(无 `sessionId`)在 `?session=` 降权投影里被擦(别的会话的子代跑什么模型 = 会话内容,与 `agentType` 同判)。
+     *  ADDITIVE / tolerate-absent。 */
+    model?: string;
     /** Owning principal (= the run's scope). The `/v1/fleet/stream` route filters to the caller's scope (owner-gated)
      *  unless the caller is fleet-wide (operator / trace-token). NOT rendered — a tenant-isolation field. */
     scope?: string;
@@ -134,8 +147,10 @@ export interface FleetTaskRow {
      *    (`${runId} ${childTaskId}`)。此形只在**没有 BCE 真行**的前台 delegation 上保留(同步腿委派的
      *    子代不过 background-child registry ⇒ 不让位就没有行);tick 点名的是 BCE 真行(后台子代的 tick 带它的行 id;workflow agent 的
      *    tick 带会话 id、经让位登记簿换成行 id),本车道**让位不铸**(双生行退役)。
-     *  消费端读法:带 `sourceLane:"run-leg"` 的行是过渡形,与 a\* 行**不会**同时描述同一个 agent;不需要再
-     *  自己发明「复合 id 首段==parentId 且撞 (parentId,name)」那类集合级判据(cli 侧的防御税)。
+     *  🔴 **这是契约形,不是过渡形**:引擎的契约是前台(同步)委派的子代 —— plain 与 fork 两腿 —— 不登 background-child registry、
+     *  没有 BCE 帧,它在舰队上的身份就是宿主由 `task_progress` 派生的这一行(`taskId` = 子会话 id)。一个子代恰一个行写者,由 id 形决定:
+     *  带 `sourceLane:"run-leg"` 的行与 a\* 行**不会**同时描述同一个 agent(偏离记录:引擎加「前台 → 后台移交」动词那一天,前台子代改登 registry 行,
+     *  本车道随之退役)。消费端不需要再自己发明「复合 id 首段==parentId 且撞 (parentId,name)」那类集合级判据(cli 侧的防御税)。
      *  ADDITIVE / tolerate-absent。 */
     sourceLane?: "run-leg";
     /**
@@ -713,7 +728,10 @@ export declare function fleetRunResiduals(result: {
         toolCalls?: number;
         costMicroUsd?: number;
     };
-} | null | undefined): FleetRunResiduals;
+} | null | undefined, 
+/** 这条 run 的失败码 —— 调用方手上的那一份:run 行喂入的 = 行的码列(`RunRecord.errorCode`,唯一读法;收割 / 判决行的 `result` 是空的,码只在列上),
+ *  活结果喂入的 = `failureCodeOf(result.terminal)`。本函数不再从 blob 读码。 */
+errorCode: string | null | undefined): FleetRunResiduals;
 /**
  * [ref]-B (core 1.240.0) — the PROCESS-LEVEL background-child fleet publisher, wired once
  * onto `RunnerDeps.onBackgroundChildEvent`. Unlike {@link fleetRunPublisher} (per-leg: dies at leg settle —

package/dist/fleet/fleet-bus.js

@@ -1,6 +1,5 @@
 import { EventEmitter } from "node:events";
 import { DURABLE_AGENT_HANDLE_RE, deriveAgentDisplayStatus, runParkedOf } from "@sema-agent/core";
-import { persistedPlaneOf } from "../terminal.js";
 import { takeWorkspaceSnapshotFailure } from "./workspace-snapshot-residual.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { redactSecrets } from "../trace/redact.js";
@@ -280,6 +279,30 @@ export function fleetRunPublisher(bus, run) {
             return u.totalTokens;
         return (u.totalInputTokens ?? 0) + (u.outputTokens ?? 0);
     };
+    const mintRunLegRow = (taskId, ev, parentId) => {
+        const cid = childId(taskId);
+        if (yieldToBackgroundChildLane(taskId, cid, ev.name))
+            return;
+        children.add(cid);
+        const childName = ev.name !== undefined ? redactSecrets(ev.name) : undefined;
+        if (!childStartedAt.has(cid))
+            childStartedAt.set(cid, Date.now());
+        const toolUses = toolUsesOf(ev.usage);
+        bus.publishTask({
+            id: cid,
+            sourceLane: "run-leg",
+            ...(childName !== undefined ? { name: childName, agentType: childName } : {}),
+            parentId,
+            scope: run.scope,
+            ...sessionField,
+            ...workflowRunIdField(ev),
+            status: tickStatus(ev.status),
+            tokens: sumTokens(ev.usage),
+            ...(typeof ev.seq === "number" ? { cycleSeq: ev.seq } : {}),
+            ...(toolUses !== undefined ? { toolUses } : {}),
+            elapsedMs: Date.now() - childStartedAt.get(cid),
+        });
+    };
     return {
         onStart() {
             bus.publishTask({ id: run.runId, ...(run.name !== undefined ? { name: run.name } : {}), ...(run.description ? { description: run.description } : {}), scope: run.scope, ...sessionField, status: "running", tokens: 0, elapsedMs: 0 });
@@ -299,14 +322,7 @@ export function fleetRunPublisher(bus, run) {
                 bus.publishTask({ id: run.runId, tokens, elapsedMs: Date.now() - startedAt });
             }
             else if (ev.type === "task_progress" && ev.taskId) {
-                const cid = childId(ev.taskId);
-                if (yieldToBackgroundChildLane(ev.taskId, cid, ev.name))
-                    return;
-                children.add(cid);
-                const childName = ev.name !== undefined ? redactSecrets(ev.name) : undefined;
-                if (!childStartedAt.has(cid))
-                    childStartedAt.set(cid, Date.now());
-                bus.publishTask({ id: cid, sourceLane: "run-leg", ...(childName !== undefined ? { name: childName, agentType: childName } : {}), parentId: run.runId, scope: run.scope, ...sessionField, ...workflowRunIdField(ev), status: tickStatus(ev.status), tokens: sumTokens(ev.usage), ...(typeof ev.seq === "number" ? { cycleSeq: ev.seq } : {}), ...(() => { const t = toolUsesOf(ev.usage); return t !== undefined ? { toolUses: t } : {}; })(), elapsedMs: Date.now() - childStartedAt.get(cid) });
+                mintRunLegRow(ev.taskId, ev, run.runId);
             }
             else if (ev.type === "tool_start" && ev.toolName) {
                 bus.publishTask({ id: run.runId, description: ev.toolName });
@@ -317,15 +333,7 @@ export function fleetRunPublisher(bus, run) {
                 return;
             if (ev.type !== "task_progress" || !ev.taskId)
                 return;
-            const cid = childId(ev.taskId);
-            if (yieldToBackgroundChildLane(ev.taskId, cid, ev.name))
-                return;
-            children.add(cid);
-            const parentId = ev.parentTaskId && ev.parentTaskId !== run.rootTaskId ? (backgroundRowOf(ev.parentTaskId) ?? childId(ev.parentTaskId)) : run.runId;
-            const fwdName = ev.name !== undefined ? redactSecrets(ev.name) : undefined;
-            if (!childStartedAt.has(cid))
-                childStartedAt.set(cid, Date.now());
-            bus.publishTask({ id: cid, sourceLane: "run-leg", ...(fwdName !== undefined ? { name: fwdName, agentType: fwdName } : {}), parentId, scope: run.scope, ...sessionField, ...workflowRunIdField(ev), status: tickStatus(ev.status), tokens: sumTokens(ev.usage), ...(typeof ev.seq === "number" ? { cycleSeq: ev.seq } : {}), ...(() => { const t = toolUsesOf(ev.usage); return t !== undefined ? { toolUses: t } : {}; })(), elapsedMs: Date.now() - childStartedAt.get(cid) });
+            mintRunLegRow(ev.taskId, ev, ev.parentTaskId && ev.parentTaskId !== run.rootTaskId ? (backgroundRowOf(ev.parentTaskId) ?? childId(ev.parentTaskId)) : run.runId);
         },
         onTerminal(status, residuals) {
             settledLeg = true;
@@ -350,9 +358,10 @@ export function fleetRunPublisher(bus, run) {
         },
     };
 }
-export function fleetRunResiduals(result) {
+export function fleetRunResiduals(result, errorCode) {
+    const stoppedBy = errorCode === "cancelled" ? { stoppedBy: "user" } : {};
     if (!result)
-        return {};
+        return stoppedBy;
     const s = result.stats;
     const usage = s
         ? {
@@ -364,7 +373,7 @@ export function fleetRunResiduals(result) {
         : {};
     return {
         ...(Object.keys(usage).length > 0 ? { usage } : {}),
-        ...(persistedPlaneOf(result).errorCode === "cancelled" ? { stoppedBy: "user" } : {}),
+        ...stoppedBy,
         ...(result.sessionId ? { transcriptId: result.sessionId } : {}),
         ...(takeWorkspaceSnapshotFailure(result.sessionId) ? { workspaceSnapshot: "failed" } : {}),
     };
@@ -426,7 +435,7 @@ export function fleetBackgroundChildPublisher(bus, log) {
         }
         return match !== undefined ? { id: match, resolved: true } : { id: parentInput, resolved: false };
     };
-    const rowTags = (m) => {
+    const rowTags = (m, e) => {
         let parentId;
         const parentInput = m.parentTaskId ?? m.parentSessionLink;
         if (parentInput) {
@@ -447,6 +456,7 @@ export function fleetBackgroundChildPublisher(bus, log) {
             ...(parentId !== undefined ? { parentId } : {}),
             ...(m.workflowRunId !== undefined ? { workflowRunId: m.workflowRunId } : {}),
             ...(m.parentToolCallId !== undefined ? { parentToolCallId: m.parentToolCallId } : {}),
+            ...(e.model ? { model: e.model } : {}),
             ...(m.spawnedAt !== undefined ? { startedAt: m.spawnedAt, elapsedMs: Date.now() - m.spawnedAt } : {}),
         };
     };
@@ -485,7 +495,7 @@ export function fleetBackgroundChildPublisher(bus, log) {
         remember(e.taskId, m);
         joinWorkflowAgentNames(e, m);
         const displayName = e.description ?? e.name;
-        bus.publishTask({ id: e.taskId, ...(displayName !== undefined ? { name: redactSecrets(displayName) } : {}), ...(e.agentType ? { agentType: redactSecrets(e.agentType) } : {}), ...(e.spawnName ? { agentName: e.spawnName } : {}), ...rowTags(m), status: "running", tokens: 0, ...(typeof e.seq === "number" ? { cycleSeq: e.seq } : {}), ...(e.transcriptId ? { transcriptId: e.transcriptId } : {}) });
+        bus.publishTask({ id: e.taskId, ...(displayName !== undefined ? { name: redactSecrets(displayName) } : {}), ...(e.agentType ? { agentType: redactSecrets(e.agentType) } : {}), ...(e.spawnName ? { agentName: e.spawnName } : {}), ...rowTags(m, e), status: "running", tokens: 0, ...(typeof e.seq === "number" ? { cycleSeq: e.seq } : {}), ...(e.transcriptId ? { transcriptId: e.transcriptId } : {}) });
         dlog("bg_child_event", { kind: "spawn", taskId: e.taskId, sessionScoped: e.sessionScoped, scope: m.tenantScope, hostSessionId: m.hostSessionId ?? null, parentTaskId: m.parentTaskId ?? null });
     };
     const handleTick = (e, m) => {
@@ -498,12 +508,12 @@ export function fleetBackgroundChildPublisher(bus, log) {
         const currentTool = e.currentTool
             ? { toolName: e.currentTool.toolName, ...(e.currentTool.target !== undefined ? { target: redactSecrets(e.currentTool.target).slice(0, 300) } : {}) }
             : undefined;
-        bus.publishTask({ id: e.taskId, ...rowTags(m), status: "running", ...(tokens !== undefined ? { tokens } : {}), ...(name ? { name } : {}), ...(agentType ? { agentType } : {}), ...(agentName ? { agentName } : {}), ...(currentAction ? { currentAction } : {}), ...(currentTool ? { currentTool } : {}), ...(typeof e.seq === "number" ? { cycleSeq: e.seq } : {}), ...(e.usage?.toolUses !== undefined ? { toolUses: e.usage.toolUses } : {}), ...(e.transcriptId ? { transcriptId: e.transcriptId } : {}) });
+        bus.publishTask({ id: e.taskId, ...rowTags(m, e), status: "running", ...(tokens !== undefined ? { tokens } : {}), ...(name ? { name } : {}), ...(agentType ? { agentType } : {}), ...(agentName ? { agentName } : {}), ...(currentAction ? { currentAction } : {}), ...(currentTool ? { currentTool } : {}), ...(typeof e.seq === "number" ? { cycleSeq: e.seq } : {}), ...(e.usage?.toolUses !== undefined ? { toolUses: e.usage.toolUses } : {}), ...(e.transcriptId ? { transcriptId: e.transcriptId } : {}) });
     };
     const handleTerminal = (e, m) => {
         const status = e.status === "completed" ? "completed" : e.status === "killed" ? "killed" : "failed";
         bus.publishTask({
-            id: e.taskId, ...rowTags(m), status,
+            id: e.taskId, ...rowTags(m, e), status,
             ...(e.spawnName ? { agentName: e.spawnName } : {}),
             ...(typeof e.seq === "number" ? { cycleSeq: e.seq } : {}),
             ...(e.stoppedBy ? { stoppedBy: e.stoppedBy } : {}),

package/dist/fleet/fleet-reconciler.js

@@ -48,7 +48,7 @@ export function createFleetReconciler(deps) {
     const upgradeWatched = (id, w, rec, trigger) => {
         if (!watch.delete(id))
             return false;
-        deps.bus.publishTask({ ...w.row, status: runStatusToFleet(rec.status), retiredBy: "reconcile", ...fleetRunResiduals(rec.result) });
+        deps.bus.publishTask({ ...w.row, status: runStatusToFleet(rec.status), retiredBy: "reconcile", ...fleetRunResiduals(rec.result, rec.errorCode) });
         deps.bus.removeTask(id, { ...(w.row.cycleSeq !== undefined ? { cycleSeq: w.row.cycleSeq } : {}) });
         lastFrameAt.delete(id);
         deps.metrics?.inc("fleet_rows_reconciled_total", { disposition: "retired_deferred", trigger });
@@ -159,7 +159,7 @@ export function createFleetReconciler(deps) {
                 id: row.id,
                 status: runStatusToFleet(rec.status),
                 retiredBy: "reconcile",
-                ...fleetRunResiduals(rec.result),
+                ...fleetRunResiduals(rec.result, rec.errorCode),
             });
             parentsOnBus.delete(row.id);
             deps.bus.removeTask(row.id, { ...(row.cycleSeq !== undefined ? { cycleSeq: row.cycleSeq } : {}) });

package/dist/fleet/serving-lease.js

@@ -1,9 +1,11 @@
-import { readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { atomicWriteFileSync } from "../plugins/owner-only-file-mode.js";
 import { SERVING_LEASE_TTL_DEFAULT_MS, readServingLeaseResponse } from "@sema-agent/settings-schema/fleet";
 import { centerFetch } from "../web-admin-client/center-request.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { leaseDrainActionId } from "./drain-entry.js";
+import { readUpstreamJson } from "../upstream-body.js";
 export const SERVING_LEASE_FETCH_TIMEOUT_MS = 5_000;
 export const SERVING_LEASE_DENIED_FILE = "fleet-serving-lease-denied.json";
 const RENEW_MIN_INTERVAL_MS = 1_000;
@@ -37,7 +39,6 @@ function denialLeadOf(d) {
 export function createServingLeaseClient(o) {
     const mono = o.clock?.mono ?? (() => performance.now());
     const epoch = o.clock?.epoch ?? Date.now;
-    const f = o.fetchImpl ?? fetch;
     const stickyPath = o.dataRoot === undefined ? undefined : join(o.dataRoot, SERVING_LEASE_DENIED_FILE);
     let capability;
     const enabled = () => capability?.announced === true;
@@ -66,10 +67,8 @@ export function createServingLeaseClient(o) {
             return false;
         }
         const record = { worker: o.center.worker, generation: o.generation, reason, at: epoch() };
-        const tmp = `${stickyPath}.tmp-${process.pid}`;
         try {
-            writeFileSync(tmp, `${JSON.stringify(record)}\n`, { mode: 0o600 });
-            renameSync(tmp, stickyPath);
+            atomicWriteFileSync(stickyPath, `${JSON.stringify(record)}\n`, { durability: "best-effort" });
             return true;
         }
         catch (err) {
@@ -105,9 +104,9 @@ export function createServingLeaseClient(o) {
         let reading;
         let why = "";
         try {
-            const { res } = await centerFetch(o.center, { kind: "fleet-serving-lease" }, { method: "POST", json: request, timeoutMs: SERVING_LEASE_FETCH_TIMEOUT_MS, fetchImpl: f });
+            const { res } = await centerFetch(o.center, { kind: "fleet-serving-lease" }, { method: "POST", json: request, timeoutMs: SERVING_LEASE_FETCH_TIMEOUT_MS, fetchImpl: o.fetchImpl });
             if (res.ok) {
-                reading = readServingLeaseResponse(await res.json().catch(() => undefined));
+                reading = readServingLeaseResponse(await readUpstreamJson(res).catch(() => undefined));
                 if (reading === undefined)
                     why = "reply is not a serving-lease verdict";
             }

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

@@ -0,0 +1,42 @@
+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: {
+    /** 分叉式回卷(会话在那条消息处分叉)。 */
+    readonly resumeAt: {
+        readonly code: "resume_at.unknown_event";
+        readonly wayOut: "give an explicit resumeAt";
+    };
+    /** 只恢复代码(提交体 `rewindFilesTo` 与 run 外口的 `to` 同族同码)。 */
+    readonly rewindFilesTo: {
+        readonly code: "rewind_files_to.unknown_event";
+        readonly wayOut: "name another prompt";
+    };
+};
+export type HistoryAnchorFamily = keyof typeof HISTORY_ANCHOR_FAMILIES;
+/**
+ * 手柄 → entry id;未知 ⇒ 抛 404(族码 + 成因半句 + 族的出路)。`owner` = 锚行的属主键(锚店的 null-safe 属主守卫):提交面传提交者,run 外口传会话属主
+ * (门已证调用方读得到这只会话;锚由这只会话的提交落下,属主键就是会话属主 —— 运维代人回退读的是同一把键)。`reader` = 收到这句 404 的那位调用方的存取器入口
+ * (只给成因半句的 run 行读用,见 {@link unknownAnchorCause}),由 {@link anchorReaderOf} 铸。
+ * `field` = 句首点名的请求字段。
+ */
+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

@@ -0,0 +1,34 @@
+import { HttpError } from "./security.js";
+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, 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}) — ${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