@sema-agent/server 7.79.0 → 7.79.1

package/dist/http/approval-sweeps.js

@@ -0,0 +1,138 @@
+import { redactHead } from "../observability/run-terminal-log.js";
+import { findParkOrigin } from "../parked-decide.js";
+import { decodeCheckpointScope } from "../security.js";
+import { personDecision } from "../host-decision.js";
+import { APPROVAL_GATE_KINDS } from "../tool-approval.js";
+import { createWallClockJumpGuard } from "../wall-clock-jump-guard.js";
+import { hasServiceAuth } from "./dispatch.js";
+import { gatedPrincipal } from "./principal-gate.js";
+export function createApprovalSweeps(ctx) {
+    const { deps, resumeCheckpoint, mayDiscloseRowError } = ctx;
+    const denySweepClockGuard = createWallClockJumpGuard({
+        slaMs: deps.config.approvalTimeoutSec > 0 ? deps.config.approvalTimeoutSec * 1000 : undefined,
+        onJump: ({ jumpMs, graceMs }) => deps.logger?.warn?.("deny_sweep_wall_clock_jump", {
+            jumpMs,
+            graceMs,
+            note: jumpMs > 0
+                ? "the wall clock stepped FORWARD relative to the monotonic clock; the approval SLA deny-sweep stands down for graceMs of MONOTONIC time so no pending gate is denied earlier than one full SLA of REAL time ([4232]①/[4235]). The checkpoint terminal_at_ms backstop is unaffected — nothing can hang forever."
+                : "the wall clock stepped BACKWARD relative to the monotonic clock; the deny-sweep needs no grace for this direction (a receding deadline only DELAYS a deny) but the step itself is an operational fact worth recording.",
+        }),
+        onSuppressed: ({ remainingMs }) => deps.logger?.info?.("deny_sweep_clock_grace", { remainingMs }),
+        onGraceCapped: ({ totalGraceMs }) => deps.logger?.warn?.("deny_sweep_clock_grace_capped", {
+            totalGraceMs,
+            note: "the wall clock kept stepping forward; the approval SLA deny-sweep has stood down for the maximum cumulative grace and now RESUMES on a demonstrably unstable clock — a fail-closed leg that never runs is worse than one running on a bad clock. Fix NTP on this host.",
+        }),
+    });
+    async function denyExpiredApprovals(now) {
+        const cs = deps.checkpointStore;
+        if (!cs)
+            return;
+        if (!denySweepClockGuard.admit(now))
+            return;
+        const expired = await cs.listExpiredApprovalGates(now).catch(() => []);
+        const isParkedOwned = async (sessionId) => {
+            if (deps.backgroundAgentStore === undefined && deps.workflowAgentSessionIndex === undefined)
+                return false;
+            try {
+                const token = await cs.findPendingTokenBySession(sessionId, undefined, { gateKinds: APPROVAL_GATE_KINDS });
+                if (!token)
+                    return false;
+                const cp = await cs.get(token);
+                if (!cp)
+                    return false;
+                return (await findParkOrigin({
+                    ...(deps.backgroundAgentStore !== undefined ? { agentStore: deps.backgroundAgentStore } : {}),
+                    ...(deps.workflowAgentSessionIndex !== undefined && deps.workflowRunStore !== undefined
+                        ? { workflowIndex: deps.workflowAgentSessionIndex, workflowRunStore: deps.workflowRunStore }
+                        : {}),
+                }, { token, scope: cp.scope, sessionId: cp.sessionId })) !== undefined;
+            }
+            catch {
+                return false;
+            }
+        };
+        let parkedSkipped = 0;
+        for (const { sessionId } of expired) {
+            if (await isParkedOwned(sessionId)) {
+                parkedSkipped += 1;
+                continue;
+            }
+            await resumeCheckpoint(sessionId, "deny", "approval SLA expired — auto-denied", { decidedBy: "sla_timeout" }).then((r) => { if (r.status >= 400)
+                deps.logger?.warn?.("deny_sweep_resume_blocked", { sessionId, status: r.status, errorCode: r.body?.errorCode }); }, (e) => deps.logger?.warn?.("deny_sweep_resume_failed", { sessionId, err: redactHead(e instanceof Error ? e.message : String(e), 2000) }));
+        }
+        if (parkedSkipped > 0)
+            deps.logger?.info?.("deny_sweep_parked_skipped", { count: parkedSkipped });
+    }
+    async function redeemParkedAsk(req) {
+        const cs = deps.checkpointStore;
+        if (!cs) {
+            return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+        }
+        if (!hasServiceAuth(deps.config) && !deps.config.allowUnauthedWrites) {
+            return { status: 503, body: { error: "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting task submissions", errorCode: "auth.service_token_required" } };
+        }
+        if (deps.drainState?.draining) {
+            return {
+                status: 503,
+                body: {
+                    error: "draining",
+                    errorCode: "draining",
+                    message: "this instance is draining for shutdown/upgrade — retry against the replacement instance",
+                    ...(deps.drainState.reason ? { reason: deps.drainState.reason } : {}),
+                },
+            };
+        }
+        if (deps.modelReady && !deps.modelReady()) {
+            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",
+                },
+            };
+        }
+        if (deps.costQuota && req.httpReq) {
+            const quotaPrincipal = gatedPrincipal(req.httpReq, deps.config);
+            if (quotaPrincipal !== undefined) {
+                const d = deps.costQuota.check(quotaPrincipal);
+                if (!d.allowed) {
+                    deps.metrics?.inc("cost_quota_rejected_total");
+                    return {
+                        status: 429,
+                        body: { error: "cost quota exceeded", errorCode: "limit.cost_quota_exceeded", usedMicroUsd: d.usedMicroUsd, limitMicroUsd: d.limitMicroUsd, retryAfterSec: d.retryAfterSec },
+                    };
+                }
+            }
+        }
+        let cp;
+        try {
+            cp = await cs.get(req.gateToken);
+        }
+        catch (e) {
+            if (!(await mayDiscloseRowError(cs, req.gateToken, { principal: req.principal, explicitOperator: false }))) {
+                deps.logger?.warn?.("parked_late_decision_unreadable_row_withheld", { askId: req.askId });
+                return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+            }
+            return { status: 409, body: { error: e instanceof Error ? e.message : String(e), errorCode: "conflict.checkpoint_unreadable" } };
+        }
+        if (!cp) {
+            return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+        }
+        const cpPrincipal = decodeCheckpointScope(cp.scope);
+        if (cpPrincipal !== undefined && cpPrincipal !== req.principal) {
+            deps.logger?.warn?.("parked_late_decision_scope_mismatch", { askId: req.askId });
+            return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+        }
+        const binding = {
+            checkpointToken: req.gateToken,
+            ...(req.gateBoundCallId !== null ? { boundCallId: req.gateBoundCallId } : {}),
+            ...(req.gateBoundInputHash !== null ? { boundInputHash: req.gateBoundInputHash } : {}),
+            ...(req.updatedInput !== undefined ? { updatedInput: req.updatedInput } : {}),
+        };
+        const out = await resumeCheckpoint(cp.sessionId, req.decision, req.note, personDecision(req.principal), req.httpReq, undefined, binding, undefined, true, { principal: req.principal, explicitOperator: false });
+        return { status: out.status, body: out.body };
+    }
+    return { denyExpiredApprovals, redeemParkedAsk };
+}
+//# sourceMappingURL=approval-sweeps.js.map

package/dist/http/dispatch.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 请求流水线(S-147 切片:`http/server.ts` 的 `handle()` 1130–1568 与它的模块级分类词表逐字搬家,正文一字未改)。
+ *
+ * 住在这里的三样东西是一件事的三个面:①`handle()` —— admission 计数 / 附着登记 / CORS / /health / /metrics /
+ * 鉴权桥 / 全局服务凭据门 / drain 与 roster-pending 两道 503 / 35 只域调用链;②`ROUTE_DOMAINS` —— 那条链的
+ * 域名册(`test/route-shape-roster.test.ts` 层D 从 handle() 真源码抽序与它对拍);③分类谓词族
+ * (`routeLabel` / `isBillableSubmitPath` / `isCredentialGatedRewrite` / `isMethodDispatchedSubmitPath` /
+ * `hasServiceAuth` / `cors` / `PROCESS_STARTED_AT_MS`)—— 流水线判「这条 url 吃哪几道门、记哪个标签」的全部词表。
+ * 留在 server.ts 则本文件必须值 import 组合根 ⇒ 闭合运行时装载环;设计稿 §5(S-146 第二刀)也正是要把
+ * ②③ 合成一张 `ROUTES` 声明表,那张表的家就是这里。公面五名由 server.ts **re-export**,消费方 import 零改动。
+ *
+ * ctx 字段 4 只(`deps` / `counters` / `noteActivity` / `routeCtxBase`),机器算(closure-free-vars)与手抄一致。
+ * `openResponses` / `lastAttachEndedAt` 是 handle 自己写的外层 `let`/`Set`,随它一起进工厂 —— 这样那两行赋值
+ * 正文一个字都不用改(装盒改写会把 `lastAttachEndedAt = …` 改成 `box.x = …`,那就不是 move 了)。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ServiceConfig } from "../config-types.js";
+import type { RouteCtxBase, RunRegistry } from "./route-ctx.js";
+import type { FlatServiceDeps } from "./server.js";
+/** POST endpoints that trigger BILLABLE work — the fail-closed auth guard must cover ALL of them (council: the
+ *  guard's inline list had drifted from the handlers and missed `/v1/approvals/:id/decide`, which resumes a run
+ *  via resumeCheckpoint/store.decide → paid tokens). Keep this in sync when adding a billable POST route. */
+/**
+ * 「这条 url **是**计费提交面,但它到底提不提交由**请求体里的方法**决定」—— 目前只有 A2A 的
+ * JSON-RPC 端点(单 URL 承载 `message/send` 写 + `tasks/get` 读,因为 agent card 只能公告一个 `url`)。
+ *
+ * 用途:两道**可用性** 503(drain / model-roster-pending)按 url 一刀切会把 `tasks/get` 这条纯读一起
+ * 关掉,而单副本部署恰好在重启/依赖降级窗口里最需要取回已完成的结果(codex 轮2 R2-3,验真后修)。
+ * 本谓词让 `handle()` 对这条 url **跳过**那两道,改由域模块在 `message/send` 分支里施加同样的两道
+ * (`routes/a2a-serve.ts` 的 `submitUnavailable`,文案逐字同源)。
+ *
+ * 🔴 **只豁免那两道,不豁免安全轴**:`isBillableSubmitPath` 本身**不变**(它仍答 true),所以
+ *  ① 无 service token 的部署上那道 fail-closed 503 照旧罩着这条 url —— 它判的是「这台机能不能收写」,
+ *    与方法无关,而且门必须在解析请求体**之前**;
+ *  ② billable 申明门钉的仍是那只纯谓词(表里 `/v1/a2a` 依旧 billable=true)。
+ * 新成员进本表 = 承诺「该域在自己的方法分支里补齐那两道」,漏补就是一条静默旁路;所以本表只该有
+ * 「单 URL 多方法」这一种成员,加一条要连同它的域内补门一起过评审。
+ */
+export declare function isMethodDispatchedSubmitPath(url: string): boolean;
+/** 「这台部署配了任何一把 service 凭证吗」—— fail-closed 写门族的真值源。**单一属主**:`handle()` 的
+ *  凭证门、[ref] 的 parked 赎回席、以及 [ref] 的 consolidation 阀门启动期告警读同一句(手抄迟早
+ *  只改一处,而这条判据决定的是「无凭证部署上写口开不开」)。导出仅为最后一个消费点(main.ts)。 */
+export declare function hasServiceAuth(config: ServiceConfig): boolean;
+export declare function isBillableSubmitPath(url: string): boolean;
+/**
+ * [ref]([ref] 件5)—— **改写门**:不烧模型、但在**没有任何 service credential** 的部署形下必须与
+ * billable / bake 两族一样 fail-closed 的写门。谓词与 `isBillableSubmitPath` **刻意分开**:这几扇门
+ * `billable=false`(零模型工作),塞进那张名单会让它们连带吃 drain 与 model-roster-pending 两道 503 ——
+ * 而收编与规则读写在排空期/roster 未落时做完全无害。
+ *
+ * 判据(两个合取项,缺一不进本表)= 「授权的唯一输入是 principal 头」∧「动作是**持久改写**」:
+ *  · `POST /v1/adoption` —— operator-only 的一次性部署级动作,把一个 principal 名下**每一行**重写到另一个
+ *    身份;授权判据 `explicitOperatorOk(gatedPrincipal(...))`。
+ *  · `POST /v1/rules/cc-import/*` —— principal lane 的**持久 allow 规则**铸造口;一条持久 allow 规则对后续
+ *    同命令的 classify 档 ask 常驻消音(core [ref] 之后仍然如此,只是不再消 mandated 的那些)。
+ *  · `DELETE /v1/rules` —— 同一个规则店的**撤销**口。方向相反(收紧)但同样是持久改写,而且它多一条
+ *    operator 超范围域(`?principal=` / body 的 `principal` 让 operator 收回**任一**租户的规则)⇒ 自造一个
+ *    列在 `OPERATOR_PRINCIPALS` 里的头,就能把每一位租户的规则一次清空。
+ * 无 service token 的部署上 `verifiedPrincipal` 走的是「BFF/gated:头已由上游验过」那一支,而这一形恰恰
+ * 是**没有**那个上游 —— 于是自造一个头就能收编别人、替任意租户种下常驻放行、或替他们全删。bake 门当年
+ * 补的就是同一句话,`isDestructiveSessionWrite` 从逐条路由白名单改成族判定也是同一句话(那次的措辞逐字是
+ * 「a forged principal header alone could **tighten/DoS** a session's tools」——撤销口落的正是 DoS 那一半)。
+ *
+ * 🔴 **方法感知**(codex 交叉复审 R2-[high],验真后修):撤销走的是 `DELETE`,而本门最初只挂在 `POST` 的
+ * 合取里 —— 于是一个自称「持久改写」的谓词把爆炸半径最大的那条动词漏在门外,正是 `isDestructiveSessionWrite`
+ * 当年被抓到的同一形。签名因此收方法,与那只谓词逐字同形。
+ * 🔴 读面**原则上**不进本表:`GET /v1/adoption/:id` 与 `GET /v1/rules` 各有自己的**属主门**兜底,本门只拦写。
+ *
+ * 🔴 **第二个合取项的加宽**(codex 交叉复审 [high],[ref] 提货批,验真后修)——判据现在是
+ * 「持久改写 **或** 授权唯一输入是 principal 头的**跨租户治理读**」。加宽是为了收进 [ref] v2-c 的两口:
+ *  · `POST /v1/memory/import` —— 直接落在**原**判据上,而且是本仓最深的那一种持久改写:它把别处铸的
+ *    条目 / 挑战 / 污染标记 / 托管链落进本部署的记忆平面。自造一个在册 operator 头 ⇒ 一份**不当调用方自制的
+ *    治理史**成为本店的账;而记忆是模型**每次挂载都读**的面,比种一条常驻 allow 规则更深(那条只影响
+ *    ask 会不会问,这条影响模型相信什么)。
+ *  · `POST /v1/memory/export` —— 是**读**,按原措辞本不该进。但被点名豁免的那两条读各有属主门兜底,
+ *    而本条**没有**:它的授权判据就是 `explicitOperatorOk`,过了就是**全库**——一次调用取走每个 scope 的
+ *    条目正文 + 托管链 + 跨会话污染标记 + lineage。把一次全租户记忆外泄留在门外、只为守住「本门只拦写」
+ *    这句措辞,是把措辞看得比它要保护的东西更重。加宽后的判据仍然是**闭**的(不是「写门以外都进」):
+ *    它要求「授权的唯一输入是那个头」∧「一次调用的爆炸半径跨租户」,`GET /v1/rules` 那种属主门读不满足。
+ * 行为面钉:`test/rewrite-door-service-token-gate.test.ts`(六扇门各一正一反 + 逃生口格 + 读面负控)。
+ */
+export declare function isCredentialGatedRewrite(method: string, url: string): boolean;
+/** Stable, low-cardinality route label for metrics/logs (ids collapsed to `:id`).
+ *  [[ref]] 字面量**先于**模式:此前模式先查,五条精确路由被形状桶吞掉(`/v1/approvals/stream`
+ *  落 ":id"、`/v1/images/{bakes,select,register}` 落 ":profile"、`/v1/images/bakes/claim` 落
+ *  "bakes/:id")——长连接 stream 的 duration 混进 :id 桶正是 fleet/stream 案的同族错桶病。
+ *  精确匹配恒比形状匹配更对,序修零反例(billable-route-declaration 门逐样本钉)。 */
+export declare function routeLabel(_method: string, url: string): string;
+export declare function createDispatch(ctx: {
+    deps: FlatServiceDeps;
+    noteActivity: (url: string) => void;
+    routeCtxBase: RouteCtxBase;
+} & Pick<RunRegistry, "counters">): {
+    handle: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+};
+//# sourceMappingURL=dispatch.d.ts.map