@sema-agent/server 7.101.1 → 7.103.0

package/dist/http/dispatch.js

@@ -3,8 +3,9 @@ import { setSsoPrincipal, ssoVerifiedPrincipal, setSsoScope, isDestructiveSessio
 import { publicStoreProbeError } from "../store-live-probe.js";
 import { looksLikeJwt } from "@sema-agent/settings-schema/api/auth-bridge";
 import { ROUTE_METHOD_ORDER } from "./route-ctx.js";
-import { PRE_CREDENTIAL_ROUTES, POST_CREDENTIAL_ROUTES, routeLabel, isBillableSubmitPath, isCredentialGatedRewrite, isMethodDispatchedSubmitPath, lookupRoute } from "./route-table.js";
+import { PRE_CREDENTIAL_ROUTES, POST_CREDENTIAL_ROUTES, routeLabel, isBillableSubmitPath, isCredentialGatedRewrite, isMethodDispatchedSubmitPath, lookupRoute, isProbePath } from "./route-table.js";
 import { sendJson, sendError, isSseResponse } from "./send.js";
+import { readinessOf, healthReadinessKeys, sendReadyz, billableRefusalOf, sendBillableRefusal } from "./readiness.js";
 import { authorized, systemFor, gatedPrincipal, sendPrincipalRefusal } from "./principal-gate.js";
 const PROCESS_STARTED_AT_MS = Date.now() - Math.round(process.uptime() * 1000);
 export function hasServiceAuth(config) {
@@ -67,7 +68,7 @@ export function createDispatch(ctx) {
         const search = qMark === -1 ? "" : rawUrl.slice(qMark);
         const allow = { pre: [], post: [] };
         noteActivity(url);
-        const admitted = method !== "OPTIONS" && url !== "/health" && !url.startsWith("/metrics");
+        const admitted = method !== "OPTIONS" && !isProbePath(url);
         if (admitted)
             counters.admittedInflight++;
         if (admitted)
@@ -89,7 +90,7 @@ export function createDispatch(ctx) {
             const status = aborted ? "499" : String(res.statusCode);
             deps.metrics?.inc("http_requests_total", { route, method, status });
             deps.metrics?.observe("http_request_duration_seconds", seconds, { route });
-            const log = route === "/health" || route === "/metrics" ? deps.logger?.debug : deps.logger?.info;
+            const log = route === "/health" || route === "/readyz" || route === "/metrics" ? deps.logger?.debug : deps.logger?.info;
             log?.call(deps.logger, "request", { method, route, status, ms: Date.now() - startedAt, ...(reqState.runStatus !== undefined ? { runStatus: reqState.runStatus } : {}), ...(reqState.runErrorCode !== undefined ? { errorCode: reqState.runErrorCode } : {}), ...(aborted ? { aborted: true, ...(reqState.streamTaskId ? { taskId: reqState.streamTaskId } : {}), ...(reqState.streamDetached ? { detached: true } : {}) } : {}) });
         };
         res.on("finish", () => record(false));
@@ -112,7 +113,7 @@ export function createDispatch(ctx) {
                 ...(deps.drainState?.draining ? { draining: true, ...(deps.drainState.since ? { drainingSince: deps.drainState.since } : {}), ...(deps.drainState.reason ? { drainReason: deps.drainState.reason } : {}) } : {}),
                 ...(deps.drainState?.inflight ? { inflight: deps.drainState.inflight() } : {}),
                 ...(deps.storeDegraded ? { durable: false, storeDegraded: true } : {}),
-                ...(deps.modelReady && !deps.modelReady() ? { ready: false, readyReason: "model roster pending (first effective-config pull)" } : {}),
+                ...healthReadinessKeys(readinessOf(deps)),
                 model: deps.config.model.id,
                 sessionBackend: deps.sessionStoreLabel ?? deps.config.sessionBackend,
                 sessions: deps.runner.sessions.size,
@@ -123,7 +124,7 @@ export function createDispatch(ctx) {
                 startedAt: PROCESS_STARTED_AT_MS,
                 port: deps.config.port,
                 ...(deps.config.directDoorActive ? { directDoorActive: true } : {}),
-                ...(restart ? { restartRequired: true, restart: { reasons: restart.reasons, version: restart.version, since: restart.since } } : {}),
+                ...(restart ? { restartRequired: true, restart } : {}),
                 ...(() => {
                     const stuck = deps.planeDeferredState?.();
                     return stuck ? { modelPlaneDeferred: { version: stuck.version, since: stuck.since, noHandoff: true, ...(stuck.blocked ? { blockedReasons: stuck.blocked } : {}) } } : {};
@@ -140,6 +141,14 @@ export function createDispatch(ctx) {
                         ...(gen.configApplyStaleMs !== undefined ? { configApplyStaleMs: gen.configApplyStaleMs } : {}),
                     };
                 })(),
+                ...(() => {
+                    const credential = deps.centerCredentialState?.();
+                    return credential ? { centerCredential: credential } : {};
+                })(),
+                ...(() => {
+                    const modelRefusals = deps.modelRefusalsState?.();
+                    return modelRefusals ? { modelRefusals } : {};
+                })(),
                 ...(() => {
                     const probe = deps.storeLiveState?.();
                     if (!probe)
@@ -152,6 +161,10 @@ export function createDispatch(ctx) {
             });
             return;
         }
+        if (req.method === "GET" && url === "/readyz") {
+            sendReadyz(res, readinessOf(deps));
+            return;
+        }
         if (req.method === "GET" && (url === "/metrics" || url === "/metrics/summary" || url === "/metrics/plan-cache")) {
             if (!deps.metrics) {
                 sendError(res, 404, "feature.metrics_disabled", "metrics disabled");
@@ -218,15 +231,12 @@ export function createDispatch(ctx) {
             sendError(res, 503, "auth.service_token_required", "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting task submissions");
             return;
         }
-        if (deps.drainState?.draining && req.method === "POST" && isBillableSubmitPath(url) && !isMethodDispatchedSubmitPath(url)) {
-            res.setHeader("retry-after", "15");
-            sendError(res, 503, "draining", "draining", { message: "this instance is draining for shutdown/upgrade — retry against the replacement instance", ...(deps.drainState.reason ? { reason: deps.drainState.reason } : {}) });
-            return;
-        }
-        if (deps.modelReady && !deps.modelReady() && req.method === "POST" && isBillableSubmitPath(url) && !isMethodDispatchedSubmitPath(url)) {
-            res.setHeader("retry-after", "5");
-            sendError(res, 503, "state.model_roster_pending", "model_roster_pending", { message: "this worker has no model yet (waiting for the first effective-config pull to land the roster) — retry shortly" });
-            return;
+        if (req.method === "POST" && isBillableSubmitPath(url) && !isMethodDispatchedSubmitPath(url)) {
+            const verdict = readinessOf(deps);
+            if (!verdict.ready) {
+                sendBillableRefusal(res, billableRefusalOf(verdict, deps.drainState?.reason));
+                return;
+            }
         }
         if (isDestructiveSessionWrite(req.method ?? "", url) && !anyServiceAuth && !deps.config.allowUnauthedWrites) {
             sendError(res, 503, "auth.service_token_required", "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting destructive session writes (policy / sync-import / fork / delete)");

package/dist/http/readiness.d.ts

@@ -0,0 +1,87 @@
+/**
+ * S-739 / S-740(车OE,7.102.0):**就绪判的唯一属主** —— 一只谓词 {@link readinessOf},全部读点经它:
+ *
+ *  ① `GET /readyz`(`dispatch.ts`,凭据门之前,与 `/health` 同位):200 `{ready:true}` / 503 `{ready:false, reasons}` ——
+ *     给**摘流**语义的探针(k8s readinessProbe / LB 健康检查);**重启**语义的探针(Docker HEALTHCHECK、k8s livenessProbe)
+ *     留在 `/health`:中心宕机时整队副本同卡 roster 未落,指 `/readyz` 就会一起重启打转(对抗复审 #6);
+ *  ② `GET /health` 的 `ready` / `readyReason` / `reasons` 三键({@link healthReadinessKeys});
+ *  ③ 计费提交门的 503(`dispatch.ts` 的 billable 门、`routes/a2a-serve.ts` 的 `message/send`、
+ *     `approval-sweeps.ts` 的 PARKED 赎回席 —— 三处同调 {@link billableRefusalOf},拒绝体只此一处铸);
+ *  ④ fleet 心跳 `InstanceAnnouncement.ready` / `draining`(`fleet-client.ts`;装配层接
+ *     `readinessOf(deployment)` —— 与 HTTP 面读的是同一个 deps 组)。
+ *
+ * 修前是四份手抄:`/health` 读 `modelReady`、计费门两道各读一只、a2a 与赎回席各抄一遍,心跳读
+ * `!isDraining()`(不含 roster)⇒ roster 未落时心跳说「就绪」而计费提交在 503,中心按心跳把它当可路由。
+ *
+ * **reasons 闭集 = `draining | model_roster_pending`,刻意不含 storeLive**(web-admin [ref] 要、[ref] 裁):
+ * DB 抖动是**共模**失效 —— 一次库抖若进就绪门,整队副本会在同一拍被 k8s / LB 摘出路由,比「打到一台库连不上
+ * 的副本」更坏。`storeLive:false` 留在 `/health` 体位 + 既有告警键,摘不摘流由读体的编排器裁(披露不代裁)。
+ * 加一个 reason = 改 {@link READINESS_REASONS} ⇒ 下面两只按 reason 穷举的表(`READY_REASON_PHRASE` 的
+ * 映射型 / `billableRefusalOf` 的 switch)当场编译红,逼你给出它的 `/health` 句与计费门拒绝体。
+ *
+ * 模块形:纯叶(只值 import `send.ts`)—— `fleet-client.ts` / `boot/` 都会读它,不许长出回环。
+ */
+import type { ServerResponse } from "node:http";
+/**
+ * 就绪原因闭集,**数组序 = 优先序**:`/health.readyReason` 取首条的句、计费门取首条的拒绝码。
+ * draining 在前 —— 一台正在下线的副本「去找替补」(Retry-After 15)比「稍后重试本机」(5)更对。
+ */
+export declare const READINESS_REASONS: readonly ["draining", "model_roster_pending"];
+export type ReadinessReason = (typeof READINESS_REASONS)[number];
+/** 就绪判。未就绪时 `reasons` 非空(类型上就是非空元组 —— 空数组的未就绪判构造不出来)、按
+ *  {@link READINESS_REASONS} 序、无重复。 */
+export type ReadinessVerdict = {
+    readonly ready: true;
+} | {
+    readonly ready: false;
+    readonly reasons: readonly [ReadinessReason, ...ReadinessReason[]];
+};
+export type NotReadyVerdict = Extract<ReadinessVerdict, {
+    ready: false;
+}>;
+/**
+ * 谓词的输入 —— `ServiceDeps` 上的同名两键(`modelReady` / `drainState`),HTTP 面与心跳读的是**同一个对象**。
+ * 两键缺席 = 该输入恒就绪(纯 env 部署没有 roster 可等;嵌入宿主 / 测试夹具没有 drain 面)。
+ */
+export interface ReadinessInputs {
+    /** boot ready 门(b):false = 布防且 roster 未落(`CONFIG_REQUIRE_ROSTER=true`)。 */
+    readonly modelReady?: () => boolean;
+    /** 收尾链翻转的共享 drain 态。 */
+    readonly drainState?: {
+        readonly draining: boolean;
+    };
+}
+/** **唯一**的就绪谓词(活判,每次调用现读输入 —— 不是快照)。 */
+export declare function readinessOf(deps: ReadinessInputs): ReadinessVerdict;
+/**
+ * `/health` 的就绪三键(additive:就绪 ⇒ 空对象,`/health` 正常形状逐字不变)。
+ * `reasons` = 与 `/readyz` 逐字同一份闭集词;`readyReason` = 首条的人读句(旧消费端读的就是它)。
+ */
+export declare function healthReadinessKeys(v: ReadinessVerdict): Record<string, unknown>;
+/** `/readyz` 两形:200 `{ready:true}` / 503 `{ready:false, reasons}` + `Retry-After: 5`。体只这两键(不带身份字段:
+ *  就绪探针给 k8s readinessProbe / Traefik / LB 摘流用,不是 `/health` 的替身;`drainReason` 等运维自由文本也不上这一面)。 */
+export declare function sendReadyz(res: ServerResponse, v: ReadinessVerdict): void;
+/** 计费提交门的拒绝(首条 reason 定码)。`retryAfterSec` 由发送形(`sendBillableRefusal`)镜像成头;交回
+ *  `{status, body}` 的赎回席只取体(它的路由刻意不带头,见 `approval-sweeps.ts` 该臂注)。 */
+export interface BillableRefusal {
+    readonly status: 503;
+    readonly body: {
+        readonly error: string;
+        readonly errorCode: string;
+        readonly message: string;
+        readonly reason?: string;
+    };
+    readonly retryAfterSec: 15 | 5;
+}
+/**
+ * 计费提交门的拒绝体 —— **唯一铸点**(`error` 字面 `"draining"` / `"model_roster_pending"` 与 `message` 是冻结的
+ * wire 契约:SDK / 壳的 pre-stream 重试按它们判型;冻结在 `test/api-error-text-freeze.test.ts` 的
+ * `FROZEN_RESULT_BODY` 与 `test/api-notice-text-freeze.test.ts` §2)。`drainReason` = `POST /v1/admin/drain`
+ * 声明的停机因由([ref],additive 键 `reason`;未声明 = 键缺席)。
+ */
+export declare function billableRefusalOf(v: NotReadyVerdict, drainReason: string | undefined): BillableRefusal;
+/** 发送形:`Retry-After` + 体(`dispatch.ts` 的 billable 门与 a2a `message/send` 同调)。走 `sendError` —— errorCode
+ *  是它的必填位置参(对抗复审 #3:修前这里是 `sendJson(res, r.status, r.body)`,与 leader 口的豁免行逐字同文,
+ *  在 error-code-key-gate 上借了别人的豁免过门);体键序与修前逐字同(`error, errorCode, message, reason?`)。 */
+export declare function sendBillableRefusal(res: ServerResponse, refusal: BillableRefusal): void;
+//# sourceMappingURL=readiness.d.ts.map

package/dist/http/readiness.js

@@ -0,0 +1,54 @@
+import { sendJson, sendError } from "./send.js";
+export const READINESS_REASONS = ["draining", "model_roster_pending"];
+export function readinessOf(deps) {
+    const [first, ...rest] = READINESS_REASONS.filter((r) => holds(r, deps));
+    return first === undefined ? { ready: true } : { ready: false, reasons: [first, ...rest] };
+}
+function holds(reason, deps) {
+    switch (reason) {
+        case "draining":
+            return deps.drainState?.draining === true;
+        case "model_roster_pending":
+            return deps.modelReady !== undefined && !deps.modelReady();
+        default: {
+            const unhandled = reason;
+            throw new Error(`readiness reason without a predicate arm: ${String(unhandled)}`);
+        }
+    }
+}
+const READY_REASON_PHRASE = {
+    draining: "draining for shutdown or upgrade",
+    model_roster_pending: "model roster pending (first effective-config pull)",
+};
+export function healthReadinessKeys(v) {
+    if (v.ready)
+        return {};
+    return { ready: false, readyReason: READY_REASON_PHRASE[v.reasons[0]], reasons: [...v.reasons] };
+}
+export function sendReadyz(res, v) {
+    if (v.ready) {
+        sendJson(res, 200, { ready: true });
+        return;
+    }
+    res.setHeader("retry-after", "5");
+    sendJson(res, 503, { ready: false, reasons: [...v.reasons] });
+}
+export function billableRefusalOf(v, drainReason) {
+    const primary = v.reasons[0];
+    switch (primary) {
+        case "draining":
+            return { status: 503, body: { error: "draining", errorCode: "draining", message: "this instance is draining for shutdown/upgrade — retry against the replacement instance", ...(drainReason ? { reason: drainReason } : {}) }, retryAfterSec: 15 };
+        case "model_roster_pending":
+            return { status: 503, body: { error: "model_roster_pending", errorCode: "state.model_roster_pending", message: "this worker has no model yet (waiting for the first effective-config pull to land the roster) — retry shortly" }, retryAfterSec: 5 };
+        default: {
+            const unhandled = primary;
+            throw new Error(`readiness reason without a billable refusal: ${String(unhandled)}`);
+        }
+    }
+}
+export function sendBillableRefusal(res, refusal) {
+    const { error, errorCode, ...extra } = refusal.body;
+    res.setHeader("retry-after", String(refusal.retryAfterSec));
+    sendError(res, refusal.status, errorCode, error, extra);
+}
+//# sourceMappingURL=readiness.js.map

package/dist/http/resume-legs.js

@@ -236,10 +236,10 @@ export function createResumeLegs(ctx) {
         const ownerLeaseAdmittedHere = req !== undefined;
         if (req !== undefined) {
             const parkedAgentStore = deps.backgroundAgentStore;
-            const parkedTool = deps.parkedReviveTool;
+            const parkedSurface = deps.parkedReviveSurface;
             const parkWarn = (event, fields) => deps.logger?.warn?.(event, fields);
             const origin = await findParkOrigin({
-                ...(parkedAgentStore !== undefined && parkedTool !== undefined ? { agentStore: parkedAgentStore } : {}),
+                ...(parkedAgentStore !== undefined && parkedSurface !== undefined ? { agentStore: parkedAgentStore } : {}),
                 ...(deps.workflowAgentSessionIndex !== undefined && deps.workflowRunStore !== undefined
                     ? { workflowIndex: deps.workflowAgentSessionIndex, workflowRunStore: deps.workflowRunStore }
                     : {}),
@@ -252,12 +252,13 @@ export function createResumeLegs(ctx) {
                 ...(answer !== undefined ? { answer } : {}),
                 ...(boundGrant ? { grantRemember: (rootSessionId) => boundGrant(rootSessionId) } : {}),
             };
-            if (origin?.kind === "background" && parkedAgentStore !== undefined && parkedTool !== undefined) {
+            if (origin?.kind === "background" && parkedAgentStore !== undefined && parkedSurface !== undefined) {
                 const parked = await withPrincipal(decodeCheckpointScope(cp.scope), () => decideParkedAgent({
                     agentStore: parkedAgentStore,
                     checkpointStore: cs,
                     registry: defaultTaskRegistry,
-                    reviveTool: parkedTool,
+                    reviveSurface: parkedSurface,
+                    ...(deps.sessionStorage?.ownerOf ? { sessionOwnerOf: deps.sessionStorage.ownerOf.bind(deps.sessionStorage) } : {}),
                     ...(deps.parkedKnownAgentTypes ? { knownAgentTypes: deps.parkedKnownAgentTypes } : {}),
                     ...(deps.parkedReviveInheritedGate ? { rebuildInheritedGate: deps.parkedReviveInheritedGate } : {}),
                     ...(deps.logger ? { warn: parkWarn } : {}),

package/dist/http/route-table.d.ts

@@ -83,6 +83,13 @@ export declare const ROUTES: readonly RouteRow[];
  *  「门前行不许出现在门后行之后」由 `test/route-order-freeze.test.ts` 钉住。 */
 export declare const PRE_CREDENTIAL_ROUTES: readonly RouteRow[];
 export declare const POST_CREDENTIAL_ROUTES: readonly RouteRow[];
+/**
+ * **探针路径**(k8s / 编排器 / 抓取器的常态高频采样):不计 admission inflight、不推活性时钟(`http/server.ts`
+ * 的 `noteActivity`)、不入附着租约集 —— 常态采样噪音不许把 SIGHUP 空闲窗 / 引擎租约的「无人使用」判据永远撑开。
+ * 两处消费(`dispatch.ts` 的 admission 门、`server.ts` 的活性时钟)读这一只;S-739 前是两份手抄
+ * (`url === "/health" || url.startsWith("/metrics")`),加 `/readyz` 时漏一份 = k8s 每 5-10s 一探就让副本永不空闲。
+ */
+export declare function isProbePath(url: string): boolean;
 /**
  * 全表 = 流水线四行 + **每一行 `ROUTES` 自己的 `decls`**,按行序摊平。
  *

package/dist/http/route-table.js

@@ -29,6 +29,7 @@ import { handleApprovalsAssistant, APPROVALS_ASSISTANT_ROUTES } from "./routes/a
 import { handleRuns, handleRunVerbs, RUNS_ROUTES, RUN_VERBS_ROUTES } from "./routes/runs.js";
 import { handleRunMemoryCapture, RUN_MEMORY_CAPTURE_ROUTES } from "./routes/run-memory-capture.js";
 import { handleMcpReconnect, MCP_RECONNECT_ROUTES } from "./routes/mcp-reconnect.js";
+import { handleBackground, BACKGROUND_ROUTES } from "./routes/background.js";
 import { handleSideQuery, SIDE_QUERY_ROUTES } from "./routes/side-query.js";
 import { handleTasks, TASKS_ROUTES } from "./routes/tasks.js";
 import { handleLeader, LEADER_ROUTES } from "./routes/leader.js";
@@ -50,6 +51,7 @@ export const ROUTES = [
     row({ handler: handleRunVerbs, decls: RUN_VERBS_ROUTES, position: "post-credential", label: "run-verbs" }),
     row({ handler: handleRunMemoryCapture, decls: RUN_MEMORY_CAPTURE_ROUTES, position: "post-credential", label: "run-memory-capture" }),
     row({ handler: handleMcpReconnect, decls: MCP_RECONNECT_ROUTES, position: "post-credential", label: "mcp-reconnect" }),
+    row({ handler: handleBackground, decls: BACKGROUND_ROUTES, position: "post-credential", label: "background" }),
     row({ handler: handleLeader, decls: LEADER_ROUTES, position: "post-credential", label: "leader", enabled: (deps) => Boolean(deps.leaderEndpoint) }),
     row({ handler: handleImages, decls: IMAGES_ROUTES, position: "post-credential", label: "images" }),
     row({ handler: handleApprovalsAssistant, decls: APPROVALS_ASSISTANT_ROUTES, position: "post-credential", label: "approvals-assistant", enabled: (deps) => Boolean(deps.checkpointStore) }),
@@ -80,10 +82,14 @@ export const PRE_CREDENTIAL_ROUTES = ROUTES.filter((r) => r.position === "pre-cr
 export const POST_CREDENTIAL_ROUTES = ROUTES.filter((r) => r.position === "post-credential");
 const PIPELINE_ROUTES = [
     { id: "health", path: "/health", methods: ["GET"] },
+    { id: "readyz", path: "/readyz", methods: ["GET"] },
     { id: "metrics", path: "/metrics", methods: ["GET"] },
     { id: "metrics-summary", path: "/metrics/summary", methods: ["GET"] },
     { id: "metrics-plan-cache", path: "/metrics/plan-cache", methods: ["GET"] },
 ];
+export function isProbePath(url) {
+    return url === "/health" || url === "/readyz" || url.startsWith("/metrics");
+}
 export const ROUTE_DECLARATIONS = [...PIPELINE_ROUTES, ...ROUTES.flatMap((r) => r.decls)];
 function declMatches(d, url) {
     if ("path" in d)

package/dist/http/routes/a2a-serve.js

@@ -6,6 +6,7 @@ import { isParkedRunStatus, isTerminalRunStatus } from "../../plugins/store-cont
 import { HttpError } from "../../security.js";
 import { scopedIdempotencyKey } from "../idempotency.js";
 import { sendJson, sendError } from "../send.js";
+import { readinessOf, billableRefusalOf, sendBillableRefusal } from "../readiness.js";
 import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 import { createDurableRun } from "./runs.js";
@@ -169,20 +170,11 @@ function rpcErrorFromTypedFailure(err, skillId) {
 }
 function submitUnavailable(res, ctx) {
     const { deps } = ctx;
-    if (deps.drainState?.draining) {
-        res.setHeader("retry-after", "15");
-        sendError(res, 503, "draining", "draining", {
-            message: "this instance is draining for shutdown/upgrade — retry against the replacement instance",
-            ...(deps.drainState.reason ? { reason: deps.drainState.reason } : {}),
-        });
-        return true;
-    }
-    if (deps.modelReady && !deps.modelReady()) {
-        res.setHeader("retry-after", "5");
-        sendError(res, 503, "state.model_roster_pending", "model_roster_pending", { message: "this worker has no model yet (waiting for the first effective-config pull to land the roster) — retry shortly" });
-        return true;
-    }
-    return false;
+    const verdict = readinessOf(deps);
+    if (verdict.ready)
+        return false;
+    sendBillableRefusal(res, billableRefusalOf(verdict, deps.drainState?.reason));
+    return true;
 }
 function readBlocking(params) {
     if (params.configuration === undefined)

package/dist/http/routes/approvals-assistant.js

@@ -289,6 +289,7 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                     ...(s.hasBidiControls === true ? { hasBidiControls: true } : {}),
                     ...(s.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
                     ...(s.mandated === true ? { mandated: true } : {}),
+                    ...(s.mandate !== undefined ? { mandate: s.mandate } : {}),
                     ...(s.denialLimitFallback !== undefined ? { denialLimitFallback: s.denialLimitFallback } : {}),
                     ...(s.origin !== undefined ? { origin: s.origin } : {}),
                     ...(s.ruleStoreUnreadable !== undefined ? { ruleStoreUnreadable: s.ruleStoreUnreadable } : {}),

package/dist/http/routes/background.d.ts

@@ -0,0 +1,80 @@
+/**
+ * S-745(core 7.32.0 #1107 的 server 半场;wire 形 [ref] / [ref] / [ref] 定)—— **会话后台任务的两只读口**:
+ *
+ *   `GET  /v1/sessions/:id/background`        → 200 `{ rows: [{ id, description?, type, status, createdAt, sessionScoped, retained? }] }`
+ *   `POST /v1/sessions/:id/background/stop`   body `{ includeRetained: boolean }` → 200 `{ receipts: [{ id, outcome }] }`
+ *
+ * 消费方:cli L-694 ①(删前核登记)/ L-686(退出三选一:「Exit and stop tasks」= `includeRetained:true`,`sema kill` =
+ * `includeRetained:false`,两臂都等受据再退)/ client-core CC-194 B 半(对账谓词)。老 server 404 ⇒ 壳只出 Stay / 退出两臂。
+ *
+ * ── 读口:逐字投 core `list()` 行 ─────────────────────────────────────────────────────────────────
+ * 读的是**进程内**注册表(`defaultTaskRegistry.list`),访问元组 = 会话自己的 `{ owner: sid, sessionId: sid, scope }`
+ * (scope = 会话行属主 `owner ?? "default"`,与 core 注册铸值同源)⇒ 可见集完全由 core 的 `canAccess` 判(fail-closed:
+ * 缺轴即拒;本会话的会话驻留行、task id 即会话 id 的 run 行、本会话发起的 workflow、根会话是本会话的后台 agent)。
+ * 键逐个处置(下面的 {@link ROW_KEY_DISPOSITION},core 给行加键 ⇒ 编译红):`task_id` 改名 `id`;`retained` **真才带**
+ * (core:缺席 ⇒ 这一行在 `includeRetained:false` 的硬面上会停);`description` 是模型写的描述、缺席时是启动时的命令文本 ——
+ * 内容族 ⇒ `redactSecrets` + 截 {@link DESCRIPTION_MAX}(显示串;core 不另存原始命令)。多副本部署:只列**本副本**上的行。
+ *
+ * ── 停止口:会话级收敛同一只函数 ────────────────────────────────────────────────────────────────
+ * `reapSessionBackgroundHard`(`background-session-reap.ts`,与 `DELETE /v1/sessions/:id` 同一只):软面(会话的后台 agent /
+ * workflow 一并结算;`includeRetained:true` 时 retain 行也先收到 SIGTERM)→ 等一次 `HOST_BG_KILL_GRACE_MS` → 硬面(车OL O1 / O2);
+ * `includeRetained` **没有缺省**(core 同一条:调用方说明这是哪一种停),缺席 / 非布尔 ⇒ 400。
+ * 受据只含 shell 行(`background_bash` / `monitor`),`outcome` 四词逐字透传:`killed` / `already_gone` / `retained_skipped` /
+ * `no_pgid`(= 没有同步硬收落地、已派普通 kill,「可能还在跑」—— 远端 / 沙箱车道的常态,不是失败)。受据在 200 之前已齐(`await`
+ * 收敛函数;有后台行时应答慢一次宽限)。
+ *
+ * ── 鉴权与门 ────────────────────────────────────────────────────────────────────────────────────
+ * 与 `POST /v1/sessions/:id/mcp/reconnect` 同一套:会话属主面缺席 ⇒ 501;未知会话与他人会话**同码同串** 404(无存在性
+ * oracle);显式 operator 可读可停任何会话(监督动作)。零模型工作 ⇒ 不进 billable、不吃 drain 503;停止口是 mutating ⇒
+ * `rateLimited`。能力位 `background: { listFace, exitFaces }` 与两口的 501 从同一个谓词推导(会话属主面在场)。
+ *
+ * 🔴 **停止口在无凭据写门内**(`credentialGated: ["POST"]`;车OL F1 = 7.102.0 合并复审 gpt-6 腿 [high]):门的两个合取项它都中
+ *   —— ① 授权的唯一输入是 principal 头(属主判 `runOwnerOk` 与 operator 臂 `explicitOperatorOk` 读的都是 `gatedPrincipal`,
+ *   无 service 凭证的部署上它收调用方自报的头);② 不可撤销、爆炸半径跨租户(知道会话 id + 自报它的属主 ⇒ 停掉那个会话的后台
+ *   进程,`includeRetained:true` 连显式 retain 的活服务一起停)。于是无 service 凭证且未开 `ALLOW_UNAUTHED_WRITES` 的部署上它与
+ *   其余改写门同码同句 503 `auth.service_token_required`(在路由之前,`dispatch.ts` 那一道),同一只会话级收敛函数的另一个调用点
+ *   `DELETE /v1/sessions/:id` 早在同一形下被 `isDestructiveSessionWrite` 拒。读口 `GET …/background` 不进:它有属主门兜底、只读、
+ *   只列本会话,与 `GET /v1/rules` 同判。已知同族缺口(不在本口单独打补丁):能力位 `exitFaces` 不含「凭据就绪」这一项,见契约
+ *   附录 B.1 `memoryCompliance` 行的同族说明。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type TaskRegistry, type BackgroundShellHardKillReceipt } from "@sema-agent/core";
+import { type RouteCtx, type RouteMatch, type RouteIdsOf } from "../route-ctx.js";
+/** `description` 的显示截断(模型描述通常一句话;回落的命令文本可能是一整段脚本)。 */
+export declare const DESCRIPTION_MAX = 500;
+/** core `list()` 的行型(从唯一的消费位取,不抄结构)。 */
+type RegistryListRow = ReturnType<TaskRegistry["list"]>[number];
+/** 读口的一行(白名单显式构造;缺席的可选键不铸)。 */
+export interface SessionBackgroundRow {
+    id: string;
+    description?: string;
+    type: RegistryListRow["type"];
+    status: RegistryListRow["status"];
+    createdAt: number;
+    sessionScoped: boolean;
+    retained?: true;
+}
+/** 停止口的一条受据(`outcome` 逐字透传 core 闭集)。 */
+export interface SessionBackgroundReceipt {
+    id: string;
+    outcome: BackgroundShellHardKillReceipt["outcome"];
+}
+/** 能力位与两口 501 的**同一个**谓词:会话属主面在场(入站 owner 门 fail-closed,缺它两口都 501)。 */
+export declare function sessionBackgroundFacesAvailable(deps: Pick<RouteCtx["deps"], "sessionStorage">): boolean;
+export declare function handleBackground(req: IncomingMessage, res: ServerResponse, match: RouteMatch<BackgroundRouteId>, ctx: RouteCtx): Promise<void>;
+export declare const BACKGROUND_ROUTES: readonly [{
+    readonly id: "session-background-list";
+    readonly pattern: RegExp;
+    readonly label: "/v1/sessions/:id/background";
+    readonly methods: readonly ["GET"];
+}, {
+    readonly id: "session-background-stop";
+    readonly pattern: RegExp;
+    readonly label: "/v1/sessions/:id/background/stop";
+    readonly credentialGated: readonly ["POST"];
+    readonly methods: readonly ["POST"];
+}];
+/** 本域可分派行的 `id` 闭集 —— handler 的 `switch` 按它判穷尽(漏一口 = 编译红)。 */
+export type BackgroundRouteId = RouteIdsOf<typeof BACKGROUND_ROUTES>;
+export {};
+//# sourceMappingURL=background.d.ts.map

package/dist/http/routes/background.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { defaultTaskRegistry } from "@sema-agent/core";
+import { reapSessionBackgroundHard } from "../../background-session-reap.js";
+import { redactSecrets } from "../../trace/redact.js";
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
+import {} from "../route-ctx.js";
+import { assertNever } from "../route-ctx.js";
+const LIST_LIMIT = 500;
+export const DESCRIPTION_MAX = 500;
+const ROW_KEY_DISPOSITION = {
+    task_id: "keep",
+    type: "keep",
+    status: "keep",
+    createdAt: "keep",
+    sessionScoped: "keep",
+    retained: "keep",
+    description: "keep",
+    toolUseId: "strip",
+    updatedAt: "strip",
+};
+void ROW_KEY_DISPOSITION;
+function projectRow(r) {
+    return {
+        id: r.task_id,
+        ...(r.description !== undefined ? { description: redactSecrets(r.description).slice(0, DESCRIPTION_MAX) } : {}),
+        type: r.type,
+        status: r.status,
+        createdAt: r.createdAt,
+        sessionScoped: r.sessionScoped,
+        ...(r.retained === true ? { retained: true } : {}),
+    };
+}
+const StopBodySchema = z.object({ includeRetained: z.boolean() }).strict();
+export function sessionBackgroundFacesAvailable(deps) {
+    return Boolean(deps.sessionStorage?.ownerOf);
+}
+export async function handleBackground(req, res, match, ctx) {
+    const { deps } = ctx;
+    const id = match.decl.id;
+    if (id === "session-background-stop" && ctx.helpers.rateLimited(req, res))
+        return;
+    const principal = gatedPrincipal(req, deps.config);
+    if (deps.config.requirePrincipal && principal === undefined) {
+        sendPrincipalRefusal(res, req, deps.config);
+        return;
+    }
+    let includeRetained = false;
+    if (id === "session-background-stop") {
+        const parsed = StopBodySchema.safeParse((await ctx.helpers.readJson(req)) ?? {});
+        if (!parsed.success) {
+            sendError(res, 400, "request.body_shape", "body must be { includeRetained: boolean } — required, no default: true = also stop the background processes this session was asked to keep running (explicit retain), false = keep them (they are reported as retained_skipped)");
+            return;
+        }
+        includeRetained = parsed.data.includeRetained;
+    }
+    const sessionId = ctx.helpers.safeDecode(match.params.sessionId);
+    if (sessionId === null) {
+        sendError(res, 400, "request.path_malformed", "session id segment is not valid percent-encoding");
+        return;
+    }
+    if (!sessionBackgroundFacesAvailable(deps)) {
+        sendError(res, 501, "capability.session_ownership_required", "the session background faces require the session-ownership face (sessionStorage.ownerOf)");
+        return;
+    }
+    const owner = await deps.sessionStorage.ownerOf(sessionId);
+    if (owner === undefined) {
+        sendError(res, 404, "not_found.session", "session not found");
+        return;
+    }
+    const isOperator = explicitOperatorOk(principal, deps.config.operatorPrincipals);
+    if (!isOperator && !ctx.helpers.runOwnerOk(req, res, owner, "session"))
+        return;
+    const scope = owner ?? "default";
+    switch (id) {
+        case "session-background-list": {
+            const rows = defaultTaskRegistry.list({ owner: sessionId, sessionId, scope }, { limit: LIST_LIMIT }).map(projectRow);
+            sendJson(res, 200, { rows });
+            return;
+        }
+        case "session-background-stop": {
+            const { receipts } = await reapSessionBackgroundHard(sessionId, scope, { includeRetained, reason: includeRetained ? "session_background_stop_all" : "session_background_stop" }, deps.logger);
+            sendJson(res, 200, { receipts: receipts.map((r) => ({ id: r.taskId, outcome: r.outcome })) });
+            return;
+        }
+        default:
+            return assertNever(id);
+    }
+}
+export const BACKGROUND_ROUTES = [
+    { id: "session-background-list", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/background$/, label: "/v1/sessions/:id/background", methods: ["GET"] },
+    { id: "session-background-stop", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/background\/stop$/, label: "/v1/sessions/:id/background/stop", credentialGated: ["POST"], methods: ["POST"] },
+];
+//# sourceMappingURL=background.js.map

package/dist/http/routes/capabilities.js

@@ -25,6 +25,7 @@ import { centerEntitlementSourceWired } from "../../runtime-caps-resolver.js";
 import { judgeAutoModeArming } from "../../auto-mode-face.js";
 import { coercePermissionModeStrict, SETTINGS_PERMISSION_MODE_WORDS } from "../../task-settings.js";
 import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
+import { sessionBackgroundFacesAvailable } from "./background.js";
 function routePairingOf(deps, name, m) {
     if (isSealedKeyPoison(deps.config.modelApiKeys?.[name]))
         return "unknown";
@@ -92,6 +93,7 @@ export async function handleCapabilities(req, res, match, ctx) {
                 sessionBackgroundable: Boolean(deps.runStore),
                 runMemoryCaptureOptOut: Boolean(deps.runStore),
                 mcpReconnect: Boolean(deps.runStore) && Boolean(deps.sessionStorage?.ownerOf),
+                background: { listFace: sessionBackgroundFacesAvailable(deps), exitFaces: sessionBackgroundFacesAvailable(deps) },
                 sharedMemory: Boolean(deps.sharedMemoryStore && deps.orgMemoryDirectory),
                 adoption: Boolean(deps.backend?.adoptionLog) && deps.config.operatorPrincipals.length > 0,
                 memoryBundle: Boolean(deps.memoryBundleExport && deps.memoryBundleImport) && deps.config.operatorPrincipals.length > 0,