@sema-agent/server 7.92.2 → 7.93.0

package/README.md

@@ -221,6 +221,7 @@ One row per endpoint family (not exhaustive):
 |-----------------|----------------|
 | `GET /health` · `GET /metrics` | Liveness + Prometheus metrics (`/metrics/summary`, `/metrics/plan-cache`) |
 | `GET /v1/capabilities` | Deployment capability discovery — what this deployment can actually do, so clients never probe 501s |
+| `GET /v1/capabilities/mcp` · `POST /v1/capabilities/mcp/probe` | Per-server MCP status with **no run required**: dial each declared server, list its tools, close it again — the first for this deployment's own declarations, the second for a caller's `.mcp.json`. Rows are the engine's own wiring-manifest rows, so a one-shot command and an interactive session read the same verdict. Rate-capped per caller and cached briefly (it really dials) |
 | `GET /v1/models` | Model catalog (names only; no gateway URLs or keys) |
 | `POST /v1/tasks` · `/v1/tasks/stream` | Synchronous task execution; SSE variant streams typed `TaskEvent`s token by token |
 | `POST /v1/runs` · `GET /v1/runs/:id` | Asynchronous runs: immediate `202`, background execution, poll for status/result |

package/README.zh-CN.md

@@ -191,6 +191,7 @@ Web search(部署 env `WEB_SEARCH_*` 七键、per-request `settings.webSearch`
 |--------|----------|
 | `GET /health` · `GET /metrics` | 存活探针 + Prometheus 指标(`/metrics/summary`、`/metrics/plan-cache`) |
 | `GET /v1/capabilities` | 部署能力发现 —— 本部署真正能做什么,客户端免 501 探测 |
+| `GET /v1/capabilities/mcp` · `POST /v1/capabilities/mcp/probe` | **无需先跑一条 run** 的逐台 MCP 状态:现连、列工具、关掉 —— 前者答本部署自己申报的服务器,后者答调用方自带的 `.mcp.json`。行就是引擎装配名册里的那一行,所以一次性命令与交互会话读到同一个判定。它会真拨号,所以按调用方限速 + 短窗复用 |
 | `GET /v1/models` | 模型目录(仅名字,不含网关 URL/key) |
 | `POST /v1/tasks` · `/v1/tasks/stream` | 同步任务执行;SSE 变体逐 token 流式输出类型化 `TaskEvent` |
 | `POST /v1/runs` · `GET /v1/runs/:id` | 异步 run:立即 `202`,后台续跑,轮询状态/结果 |

package/dist/approval-card.d.ts

@@ -21,7 +21,7 @@
  * 没有方法、没有捕获的行为。
  */
 import { z } from "zod";
-import { type AskEvidenceAbsence, type AskRequest as CoreAskRequest, type ReadRootGrantCandidate, type RuleOffer } from "@sema-agent/core";
+import { READ_ROOT_CANDIDATE_DIR_MAX, type AskEvidenceAbsence, type AskRequest as CoreAskRequest, type ReadRootGrantCandidate, type RuleOffer } from "@sema-agent/core";
 import type { AskRow } from "./plugins/approval-ask-store-sql.js";
 /** 模型自由文本(`sourceAgentName` / `delegation.agentName`)的限长(设计稿 §6.2)。设计 §3.1 把
  *  「限长 + 脱敏」写成 **server 新增责任**(引擎无此层):spawning model 挑的名字是自由文本,
@@ -270,15 +270,19 @@ export type ProbeCauseProjection = z.infer<typeof ProbeCauseSchema>;
  */
 export declare function readProbeCause(req: unknown): ProbeCauseProjection | undefined;
 /**
- * [ref](core 7.19.0)—— `readRootCandidate.dir` 的**上限**。core 自己的同族界是
- * `READ_ROOT_CANDIDATE_DIR_MAX = 1024`(`src/core/read-root-candidate.ts`),**未从包根导出**,故钉本地
- * 孪生 + 本出处注记(与 `MAX_SKILL_CONTENT_CHARS` 同款处置)。
+ * [ref](core 7.19.0)—— `readRootCandidate.dir` 的**上限**。
+ *
+ * 🔴 **本地孪生退役,改读 core 的导出**(core 7.26.0 / S-538 ⓐ,[ref] 手抄投影下线):此前这里是
+ * `export const MAX_READ_ROOT_CANDIDATE_DIR = 1024`,注里写着「core 的 `READ_ROOT_CANDIDATE_DIR_MAX`
+ * **未从包根导出**,故钉本地孪生」—— 那句话在 7.26.0 起是过期的,而一份手抄的界与它的属主分家时**不会红**:
+ * core 把界调宽,本仓照旧按旧数扣掉一个 core 认可的目录(卡上少一条出路,而人只会读成「没有出路」)。
+ * 旧名整条删、不留别名(硬 breaking 三句:本常量是 server 内部导出,零外部消费者,tsc 红即通知)。
  *
  * 🔴 超限的方向是**整只丢,不截** —— core 契约 `shell.read_boundary.grant_candidate_is_the_grant`:卡上
  * 显示的串就是人要加进读目录的那个串,截过的目录是**另一个**目录,加进去也清不掉这只 ask。与
  * {@link MAX_PROBE_CAUSE_CODE} 的 `code` 超限整只丢逐字同判据。
  */
-export declare const MAX_READ_ROOT_CANDIDATE_DIR = 1024;
+export { READ_ROOT_CANDIDATE_DIR_MAX };
 /** 窄读的输出形 —— **就是 core 的那只型**,不在本仓再声明一份同形结构(重声明 = 上游改形那天本仓静默不红)。 */
 export type ReadRootCandidateProjection = ReadRootGrantCandidate;
 /**
@@ -287,7 +291,7 @@ export type ReadRootCandidateProjection = ReadRootGrantCandidate;
  *
  * 🔴 **零判读**:server 既不从命令文本重推目录、也不校验它是不是真的能清掉这只 ask —— 那是 core 已经
  * 做过的判断(它把提议的根放回读边界又走了一遍),在下游再判一次就是同一个事实的第二个判官。
- * 🔴 形不合 ⇒ **按缺席处置**;超限 ⇒ **整只丢**(见 {@link MAX_READ_ROOT_CANDIDATE_DIR})。
+ * 🔴 形不合 ⇒ **按缺席处置**;超限 ⇒ **整只丢**(界见 {@link READ_ROOT_CANDIDATE_DIR_MAX},core 的属主值)。
  * 🔴 **缺席不是断言**:它同时覆盖「这一族 ask 没有任何目录能清掉」(敏感路径 deny 行、读边界压根读不懂
  * 的命令、递归遍历、非读边界 ask……)与「老引擎」两形 —— 消费端只读在场,永远不读缺席。
  *
@@ -814,5 +818,4 @@ export declare function buildApprovalPreambleSseFrames(frames: readonly Approval
     event: string;
     data: unknown;
 }>;
-export {};
 //# sourceMappingURL=approval-card.d.ts.map

package/dist/approval-card.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ASK_EVIDENCE_ABSENCE_VALUES, MAX_RULE_TEXT_CHARS } from "@sema-agent/core";
+import { ASK_EVIDENCE_ABSENCE_VALUES, MAX_RULE_TEXT_CHARS, READ_ROOT_CANDIDATE_DIR_MAX } from "@sema-agent/core";
 import { redactSecrets } from "./trace/redact.js";
 import { recordFailOpen } from "./observability/fail-open.js";
 import { PERSISTED_RULE_MATCHES, UNCOVERED_SEGMENT_REASONS } from "./permission-rule-vocab.js";
@@ -160,7 +160,7 @@ export function readProbeCause(req) {
         ...(raw.further !== undefined ? { further: family(raw.further) } : {}),
     };
 }
-export const MAX_READ_ROOT_CANDIDATE_DIR = 1024;
+export { READ_ROOT_CANDIDATE_DIR_MAX };
 const ReadRootCandidateEnvelopeSchema = z.object({
     readRootCandidate: z.object({ dir: z.string().min(1), clearsThisAsk: z.literal(true), covers: z.literal("exact").optional() }).optional(),
 });
@@ -169,7 +169,7 @@ export function readReadRootCandidate(req) {
     const raw = parsed.success ? parsed.data.readRootCandidate : undefined;
     if (raw === undefined)
         return undefined;
-    if (raw.dir.length > MAX_READ_ROOT_CANDIDATE_DIR)
+    if (raw.dir.length > READ_ROOT_CANDIDATE_DIR_MAX)
         return undefined;
     return { dir: raw.dir, clearsThisAsk: true, ...(raw.covers !== undefined ? { covers: raw.covers } : {}) };
 }

package/dist/boot/resolve-spec.js

@@ -296,6 +296,7 @@ export function createResolveSpec(ctx) {
             ...(effMode ? { shellGate: shellGateForMode(effMode) } : {}),
             ...((f) => (f !== undefined ? { writeFace: f } : {}))(effMode !== undefined ? writeFaceForMode(effMode) : undefined),
             ...((f) => (f !== undefined ? { autoModeRequested: f } : {}))(effMode !== undefined ? autoModeRequestedForMode(effMode) : undefined),
+            ...(body.approverPosture !== undefined ? { approverPosture: body.approverPosture } : {}),
             selfOrchestration: selfOrchestrationFromBody({ selfOrchestration: body.selfOrchestration === true || parsedSettings.settings?.ultracode === true }, config, Boolean(centerRuntimeCapsResolver)),
             forwardSubagentEvents: body.forwardSubagentEvents === true ? true : undefined,
             retainSubagentSessions: normalizeRetainSubagentSessions(body.retainSubagentSessions),

package/dist/capabilities/mcp-probe.d.ts

@@ -0,0 +1,290 @@
+/**
+ * S-481 —— **无 run 可读的逐台 MCP 状态面**的 server 半场(设计稿 `2026-09-19-s481-mcp-status-face-v1`)。
+ *
+ * ## 病(deploy 报案 I-1 / cli L-303)
+ * 壳的一次性命令(`sema mcp list`)与交互会话对同一台 MCP 服务器给出**相反**的答案:命令行报 Failed、
+ * 会话里那台 server 的工具却能用。根因不是判定不同,而是**没有面** —— 一个从未起过 run 的会话在本服务上
+ * 只有 `GET /v1/capabilities.mcp` 那一枚布尔,壳只能自己去拨号、自己造词。
+ *
+ * ## 这里立的两条面(词表与行形与 run 完全同源)
+ *  · `GET  /v1/capabilities/mcp`       —— 本部署**中心配置**的逐台状态;
+ *  · `POST /v1/capabilities/mcp/probe` —— 探测**调用方自带**的规格(壳的 `.mcp.json`)。
+ *
+ * ## 🔴 一条铸点纪律:**本模块一行都不拼**
+ * 行 = core 7.26.0 `probeMcpServers` 的 `entries`,那是 `mcpManifestEntries` 的产物,**逐字**等于一条
+ * 准备好的腿推上 `wiring_manifest.mcp[]` 的那些行(core `@contract` 原话:same projection, same failure
+ * vocabulary, same neutralized and bounded remote text)。server 若自己按 `McpServerStatus` 拼一份,那就是
+ * 同一个语义面上的**第二份**铸点 —— 它与引擎面的漂移没有任何门看得见(既有 `GET /v1/sessions/:id/mcp`
+ * 面板正是那一形,它的行是手拼的;本面刻意不沿用它,理由记在 DEBTS 而不是在这里再复制一遍)。
+ *
+ * ## 亲核到的 core 签名(7.26.0 `dist/core/mcp-probe.d.ts`,**以 d.ts 为准**)
+ *   `probeMcpServers(specs: readonly McpServerSpec[], opts?: McpProbeOptions): Promise<McpProbeResult>`
+ * 设计小稿写的是 `probeMcpServers(specs, principal, opts)` —— **d.ts 赢**:`principal` 在 `opts` 里,不是
+ * 第二个位置参。`{ entries, servers }` **恒与 `specs` 同序同长**(`@contract mcp.probe.index_aligned`),
+ * 失败台占位带 `errorCode` ⇒ 消费方按**下标**对拍,不按 `name`(名不保证唯一)。
+ *
+ * ## 三问(behavior-facing,契约与 DEPLOY-PREREQS 同文)
+ *  · **谁需要**:壳的一次性命令与交互车道要同源(同一台 server、同一套词表、同一个判定);
+ *  · **谁受伤**:探测是**真拨号**(HTTP 连接 / stdio 起子进程),被滥用就是探测风暴与子进程堆积;
+ *  · **什么补偿**:每 principal 固定限速({@link MCP_PROBE_RATE_POLICY})+ 同规格 30s 有界缓存
+ *    ({@link MCP_PROBE_CACHE_TTL_MS} / {@link MCP_PROBE_CACHE_MAX_ENTRIES},single-flight)+ 每台裁决有上界
+ *    ({@link MCP_PROBE_VERDICT_TIMEOUT_MS})+ 自带规格那一口整条被 {@link mcpInjectionHonored} 挡在多租户
+ *    之外。**如实交代**:core 的 `timeoutMs` 界的是**裁决**不是拨号,而一个答完握手就卡住 SEND 的对端
+ *    在 core 那边没有任何期限(core `docs/KNOWN-LIMITS.md`)—— 那一形上本面同样没有期限,补偿只有限速与缓存。
+ */
+import { type McpServerSpec } from "@sema-agent/core";
+/**
+ * 本面的**拒码闭集**(设计稿 §2 的四枚)。闭集写成型,是为了让 {@link MCP_PROBE_HTTP_STATUS} 那张表
+ * 「漏一枚 = 编译红」—— [ref] 的安全轴纪律:词表是闭集,未处置的成员必须是编译错误而不是运行期惊喜。
+ */
+export declare const MCP_PROBE_REFUSAL_CODES: readonly ["capability.mcp_injection_required", "limit.rate_exceeded", "request.body_shape", "request.field_invalid", "state.mcp_probe_incomplete"];
+export type McpProbeRefusalCode = (typeof MCP_PROBE_REFUSAL_CODES)[number];
+/**
+ * 🔴 **状态档取单表**(`GOVERNANCE_HTTP_STATUS` 的同族形,S-201② 的那条律):一个码在本服务上只有**一个**
+ * 状态,而路由层**一个字面量都不许手写**。写成 `as const satisfies` 两头都占:格是字面量型(直接当
+ * `sendError` 的状态参数用,零 `?? 400` 兜底 —— 兜底就是第二份真源),`satisfies` 保住闭集门。
+ */
+export declare const MCP_PROBE_HTTP_STATUS: {
+    readonly "capability.mcp_injection_required": 501;
+    readonly "limit.rate_exceeded": 429;
+    readonly "request.body_shape": 400;
+    readonly "request.field_invalid": 400;
+    readonly "state.mcp_probe_incomplete": 503;
+};
+/**
+ * 每 principal 的固定窗限速。**刻意不挂任何无关旋钮**(S-470 的同一条教训,`DEVICE_ENROLL_RATE_POLICY`
+ * 先例):全局 `RATE_LIMIT_RPM` 缺省是 `0` = 关断,把一条真拨号的面挂在它上面 = 出厂形不限速。
+ * 12/60s 是**安全地板**,不是可调参数;窗是**每副本**的(多副本部署上有效上界 = 12 × 副本数,如实记)。
+ */
+export declare const MCP_PROBE_RATE_POLICY: {
+    readonly limit: 12;
+    readonly windowMs: 60000;
+};
+/** 同 principal 同规格的结果复用窗(设计稿 §3)。命中**不计**限速、**回原 `probedAt` 时刻**。 */
+export declare const MCP_PROBE_CACHE_TTL_MS = 30000;
+/** **已落地**结果的条数硬帽 —— 一只缓存自己绝不能变成资源耗尽点(`createFixedWindowRateLimiter` 同一条有界形)。 */
+export declare const MCP_PROBE_CACHE_MAX_ENTRIES = 256;
+/**
+ * **同时在跑**的走查条数硬帽(codex r1 [high] 的第二半)。
+ *
+ * 为什么它必须是一道**拒**、不能靠逐出:在途的那一格**就是** single-flight 本身,把它从表里逐出去等于
+ * 撤掉这条面唯一的「同一份申报只拨一次」保证 —— 而那正是这道帽本来要保护的资源(连接 / 子进程)。
+ * ⇒ 帽满时**响亮拒**(429 + 退避提示),让调用方稍后再问,而不是悄悄多开一次拨号。
+ * 数字取限速额度的量级(12/60s/身份):在一台健康的部署上一次走查以毫秒~秒计,这道帽结构上摸不到;
+ * 摸到它就说明这台机器上真的有一批拨号卡着,而那时候**少开**才是对的方向。
+ */
+export declare const MCP_PROBE_MAX_INFLIGHT = 32;
+/**
+ * 每台**裁决**上界,喂 core 的 `opts.timeoutMs`。
+ *
+ * 🔴 **不是新旋钮**:没有 env、不进 config-catalog、部署方改不了它 —— 「不新铸旋钮」这条要求管的是
+ * **旋钮**,不是常量。数值与既有 `GET /v1/sessions/:id/mcp` 面板的物化上界同阶(那边 10s),而**名字刻意
+ * 独立**:本仓 `sessions.ts` 的四枚同族时限逐字写着理由 ——「两条腿的物化成本不同族,将来任一侧调窗时不该
+ * 被另一侧的名字绑架」。那边界的是**整次物化**,这边界的是**每台的裁决**,连语义都不是一回事。
+ *
+ * ⚠️ core 的硬条款(d.ts 逐字):`timeoutMs` 界**裁决**不界**拨号** —— 被时钟放弃的那次拨号仍在跑,
+ * core 在它落地时才 dispose。所以本面的「探测完零遗留」有一个**残留上界**,不是「立刻」:见 {@link MCP_PROBE_RESIDUE_SLACK_MS}。
+ */
+export declare const MCP_PROBE_VERDICT_TIMEOUT_MS = 10000;
+/**
+ * **整次走查**的上界(本面自己的钟,不是 core 的)—— **按申报条数派生**,不是一个魔法常量。
+ *
+ * 🔴 为什么非有这口钟不可(异源复核 [high],亲读 core d.ts 后确认):core 的 `timeoutMs` 界的是**每台的裁决**,
+ * 而整次调用**不会**在最后一次拨号落地之前 resolve —— 而「答完握手就卡住发送」的那一形在 core 那边
+ * **没有任何期限**(`docs/KNOWN-LIMITS.md`)。没有本钟时:那只 promise 永不落地 ⇒ 它永久占住一个缓存格与
+ * 一个在途位,而每一个后来问同一份申报的请求都会 join 上它、跟着一起永久挂住。
+ *
+ * 🔴 为什么**派生**而不是钉一个数:钉死的那个数必须照最大申报(32 台)取,于是一次**只问一台**的请求要
+ * 白等 60s 才被告知「答不出来」—— 一个与它问的东西无关的宽限。派生式 = `ceil(n / 并发) × 每台裁决 + 收尸阶梯`,
+ * 与 core 自己成文的走查时长公式**逐字同形**(d.ts:"its own duration is those per-dial times summed over
+ * `ceil(n / concurrency)` rounds"),所以在一台**对端会答或会失败**的部署上这口钟结构上摸不到 —— 摸到它
+ * 就是真有一台对端在卡发送。读数:1 台 ⇒ 14s;32 台 ⇒ 44s。
+ * 兄弟先例:`GET /v1/sessions/:id/mcp` 面板的 `MCP_MATERIALIZE_TIMEOUT_MS`(那边界的也是整次物化,但它是
+ * 一个定值;本面的申报条数由调用方决定,所以定值在这里就是那个「与所问无关的宽限」)。
+ * **纯数据** ⇒ `build*`。
+ */
+export declare function buildMcpProbeWalkTimeoutMs(declarations: number): number;
+/**
+ * 一次走查里**同时追裁决**的台数,喂 core 的 `opts.concurrency`。
+ *
+ * 为什么不用缺省的 1:core 的 d.ts 明写整次调用的时长 = 每台时长在 `ceil(n / concurrency)` 轮上的和。
+ * 缺省 1 下一个 32 台(={@link MAX_REQUEST_MCP_SERVERS})的申报最坏是 32 × {@link MCP_PROBE_VERDICT_TIMEOUT_MS}
+ * —— 一条 HTTP 请求挂五分钟。8 把最坏收进 4 轮。代价 core 也写明了:并发只影响 `connectMs` 这个读数的
+ * 争用度,**行与下标对齐不受影响**(而本面根本不发 `connectMs`)。
+ * ⚠️ 它**不是**「同时开几条传输」的帽:被时钟放弃的拨号仍在飞,最坏可达一条/台申报(core 原话)。
+ */
+export declare const MCP_PROBE_CONCURRENCY = 8;
+/**
+ * 「探测完子进程零遗留」的**残留上界**(判据 G6 用它,**不自定**)。
+ *
+ * 逐字抄 core 7.26.0 CHANGELOG 的「界」句与 `mcp-probe.d.ts` 的 `@contract mcp.probe.zero_residue_bound`:
+ * *the stdio close ladder then adds ≤ 4 000 ms (SIGTERM, then SIGKILL)*,整句是
+ * *that dial's residue is gone within `max(timeoutMs, the handshake budget + the listing budget) + 4 000 ms`*。
+ * 4 000 就是那个 `+ 4 000 ms`;同一句话的另一半 —— *a server that exits when its input closes is gone at
+ * return* —— 是规矩服务器的那一形(G6 的正控钉在这一半上)。
+ */
+export declare const MCP_PROBE_RESIDUE_SLACK_MS = 4000;
+/** 观测计数的 `outcome` 闭集(`mcp_probe_total{outcome}`)。 */
+export declare const MCP_PROBE_OUTCOMES: readonly ["probed", "cached", "empty", "gate_closed", "rate_limited", "bad_request", "failed"];
+export type McpProbeOutcome = (typeof MCP_PROBE_OUTCOMES)[number];
+/** 两条面的**同一个**体形(设计稿 §2:`POST` 回「200 同形体」)。行**只**来自 core 的 `entries`。 */
+export interface McpProbeFaceBody {
+    /** 这份读数是**哪一刻**的(缓存命中回原时刻 —— 一个复用的答案假装自己是新的,就是一条假事实)。 */
+    readonly probedAt: string;
+    /** 这份读数还能复用多久(秒)= {@link MCP_PROBE_CACHE_TTL_MS}。 */
+    readonly ttlSec: number;
+    /**
+     * 逐字 = `wiring_manifest.mcp[]` 在 wire 上的那一行 —— **同一只投影**
+     * ({@link projectWiringManifestMcpRows},契约 §G.7),不是本面自己挑的一份键。与入参申报**同序同长**
+     * (core `@contract mcp.probe.index_aligned`;下标对齐,不按 name)。
+     *
+     * 🔴 **`error`(远端原话)因此在本面上同样缺席**,而这**不是**本车的选择:§G.7 第 3 条是一条成文裁定
+     * —— 那一格是这帧上唯一的远端作者自由文本,core 7.5.0 [ref] 已把 MCP 远端错误文本的脱敏收敛到**一个**
+     * 铸点,server 在读面再脱一遍就是同一语义面的第二个写者(两遍脱敏的重叠通常比原缺陷更坏且静默)。
+     * 本车的 G7 当场量到了这条裁定的分量:不走这只投影时,一条 `http://user:pw@host` 形申报的**用户名**
+     * 会逐字上 wire(core 的中立化只遮口令位)。可操作的因由在 `errorCode` 闭集上;要远端原话得先走
+     * §G.7 第 3 条那条「带触发条件的裁定」。
+     */
+    readonly servers: readonly Record<string, unknown>[];
+}
+/** 一次拒绝的**结构性**产物:码 + 句 + 可机读的键名表(消费端不必解析文案)。状态由 {@link MCP_PROBE_HTTP_STATUS} 单表答。 */
+export interface McpProbeRefusal {
+    /** 🔴 键名是 `errorCode`,**不是** `code`:3.0.0 起 wire 错误体只有一个机器判别键,`test/error-code-key-gate.test.ts`
+     *  连「错误体附近的对象字面量里出现 `code:`」都拦(本批红先实证:第一版写成 `code` 当场被那道门逮住)。 */
+    readonly errorCode: McpProbeRefusalCode;
+    readonly message: string;
+    /** `request.body_shape` 专用:词表外 / 本面不接线的键,全路径形(已清洗+截断+排序+封顶)。 */
+    readonly unknownKeys?: readonly string[];
+}
+/**
+ * `POST …/probe` 的体读器:闭形、逐条点名、零静默丢。成功 ⇒ 交给 core 的 `specs`(**原样**转发被读出来的
+ * 条目,`McpServerSpec` 的可选键一个都不重写 —— 重写就是在 core 的型上做第二次投影)。
+ */
+export declare function readMcpProbeBody(raw: unknown): {
+    ok: true;
+    specs: McpServerSpec[];
+} | {
+    ok: false;
+    refusal: McpProbeRefusal;
+};
+/**
+ * 本面**唯一**的调用方身份归一(异源复核 [low]:此前缓存键用 `principal ?? ""`、限速键用 `… : "local"`
+ * —— 两份归一,于是一个 principal **字面就叫 `local`** 的调用方与「无 principal」共用同一个限速窗,
+ * 而缓存键又不撞。⇒ 两条键从此读同一只函数)。
+ *
+ * 无 principal(单用户部署上恒如此)折成 `local`:那台机器上只有一个人。
+ */
+export declare function buildMcpProbeIdentity(principal: string | undefined): string;
+/** 缓存键 = `(身份, sha256(规范化 specs))`。**纯数据** ⇒ `build*`。 */
+export declare function buildMcpProbeCacheKey(principal: string | undefined, specs: readonly McpServerSpec[]): string;
+/** 限速键(设计稿 §3:`mcp-probe:<身份>`)。**纯数据** ⇒ `build*`。 */
+export declare function buildMcpProbeRateKey(principal: string | undefined): string;
+/** 本域独占的运行期状态(每 server 实例一份 —— 模块级会把缓存与限速窗跨实例串味)。 */
+export interface McpProbeLocal {
+    /**
+     * 固定窗限速({@link MCP_PROBE_RATE_POLICY});键由 {@link buildMcpProbeRateKey} 铸。
+     *
+     * 🔴 实现**不在本文件**:它是既有的 {@link createFixedWindowRateLimiter}(device 注册口那一只)。
+     * 异源复核 [high] 逐行对出本文件此前手抄了同一套算法(同一份 `{startedAtMs,count}`、同一个
+     * `MAX_WINDOWS = 10_000`、同一句「过期先清、仍超清最旧一半」、同一个 `retryAfterSec` 算式),而注里
+     * 还**引着**那只函数的名字 —— 一条规则两份实现、没有任何编译期连接,正是 [ref] 的第一排查点。
+     */
+    check(key: string): Promise<{
+        allowed: boolean;
+        retryAfterSec?: number;
+    }>;
+    /**
+     * single-flight + TTL 的结果表;命中回**同一只** promise(并发首拨塌成一次走查)。
+     *
+     * 🔴 **两条判据,不是一条**(codex 对抗复审 r1 [high],亲跑复现后按类修):
+     *  · 这一格**还在跑** ⇒ 恒命中,**与年龄无关** —— 它就是 single-flight 本身;
+     *  · 这一格**已落地** ⇒ 从**落地那一刻**起算 {@link MCP_PROBE_CACHE_TTL_MS}。
+     * 修前的起点是**拨号开始**那一刻,于是一次跑得比窗口长的走查(慢服务器 / 卡住的对端)30s 之后从表里
+     * 消失而它还在跑 ⇒ 同一份申报的下一次请求另起一次走查,single-flight 恰好在最该生效的那一形上失效,
+     * 连接与子进程按限速额度叠加。红先读数(G5-bis):一台答完握手就不再答列表的 stdio 服务器,两次请求
+     * 之间跨过窗口 ⇒ **两个**子进程。
+     */
+    cached(key: string, now: number): Promise<McpProbeFaceBody> | undefined;
+    /**
+     * 登记一次走查。🔴 **格的寿命由 `walk.dials` 驱动,不由 `walk.answer` 驱动**(合并树 codex ① [high]):
+     *  · `dials` 还没落地 ⇒ 这一格**在途**:恒命中(同规格不再拨号)、不计复用窗、算一个在途位;
+     *  · `dials` **resolve** ⇒ 从那一刻起算 {@link MCP_PROBE_CACHE_TTL_MS}(正常的结果复用);
+     *  · `dials` **reject** ⇒ 整格丢掉(下一次请求重新拨,而不是被一条缓存起来的失败钉住半分钟)。
+     * 应答面(`answer`)可能**早于** `dials` 就有结论(本面的期限到点)—— 那一段窗口里这一格仍然是「在途」,
+     * 后来者拿到的是**同一只** `answer`(立刻那句 503),资源计数也仍然算着它。
+     */
+    remember(key: string, at: number, walk: McpProbeWalk, now?: () => number): void;
+    /** 缓存里现在有几条(判据面读它,不去摸内部表)。 */
+    size(): number;
+    /** 现在有几次走查**还在跑**(帽 = {@link MCP_PROBE_MAX_INFLIGHT};判据面读它,不去摸内部表)。 */
+    inflight(): number;
+}
+/** 带行为的东西 ⇒ `create*`(工厂命名律:`build*` 出纯数据,`create*` 出活对象)。 */
+export declare function createMcpProbeLocal(): McpProbeLocal;
+/**
+ * 一次走查。**两只 promise,两件事**(合并树 codex ① [high],亲跑复现后按类修):
+ *  · `answer` —— **HTTP 应答面**:到本面的期限就 reject {@link McpProbeIncomplete},调用腿据它答 503;
+ *  · `dials` —— **拨号生命周期**:core 真的把它开过的每一条都 dispose 完了才 settle。
+ *
+ * 🔴 为什么必须分家(修前是同一只):core 的拨号**不收取消**、要等 dial 落地才 dispose,所以「本面不再等它」
+ * 与「那条连接已经没了」是**两个时刻**。修前两者共用一只 promise ⇒ 超时那一拍就把缓存格与在途计数一起释放:
+ * ① 那条**仍然开着**的拨号不再计入在途帽,② 同规格重试会**重新拨一次**。对一个握手后卡 SEND 的对端,
+ * 限速只能降累积速度、限不住资源**总量** —— 红先实测:反复问同一份申报,对端存活连接从 1 涨到 6。
+ * 分家之后:在途格与资源计数**直到 `dials` 落地才释放**,期间同规格请求挂在**同一只** `answer` 上
+ * (立刻拿到那句 503,不再拨号)。
+ *
+ * `entries` 一个字都不改写(不排序、不过滤、不补键):它与入参 `specs` 同序同长是 core 的成文契约,
+ * 消费方按**下标**对拍自己的申报表。**带行为** ⇒ `create*`。
+ */
+export interface McpProbeWalk {
+    readonly answer: Promise<McpProbeFaceBody>;
+    readonly dials: Promise<unknown>;
+}
+export declare function createMcpProbeWalk(specs: readonly McpServerSpec[], principal: string | undefined, now?: () => number): McpProbeWalk;
+/** 整次走查没在 {@link MCP_PROBE_WALK_TIMEOUT_MS} 内落地。**具名型**而不是一个字符串比较:调用腿要据它
+ *  分诊(503 + 退避),而按错误文案分诊是本仓明令不许的形。 */
+export declare class McpProbeIncomplete extends Error {
+    readonly boundMs: number;
+    constructor(boundMs: number);
+}
+/** 整次走查超界那一句。**不是**「探测失败」——它说的是「这台机器现在答不出来,稍后可能就能」。 */
+export declare function buildMcpProbeIncompleteRefusal(boundMs: number): McpProbeRefusal;
+/** 零申报时的诚实空面(**不**进缓存、**不**占限速:一次没有拨号的回答不该消耗任何配额)。 */
+export declare function buildEmptyMcpProbeFace(now?: number): McpProbeFaceBody;
+/**
+ * {@link mcpInjectionHonored} 为假时那一句 —— **三条否决各自点名**(多租户 / 锁 / 合规档位),因为调用方
+ * 的下一步动作三条各不相同,而一句「not honored」把三件事压成一件。码只有一枚:消费端的分支是同一个
+ * (换部署形态 / 改旋钮,而不是重试)。
+ */
+export declare function buildMcpInjectionRefusal(): McpProbeRefusal;
+/**
+ * 限速那一句。与上面三只同住一个模块,是本面**四句 wire 文案的唯一属主** —— 一条面的措辞散在路由体里,
+ * 下一个人改一个字时没有任何地方会红。
+ *
+ * ⚠️ **如实交代一条覆盖边界**:全仓的 `api-error-text-freeze` 门锚的是 `sendError(res, <字面三位数>,
+ * "<字面码>", …)`,而本面刻意**不在调用点写字面状态**(状态从 {@link MCP_PROBE_HTTP_STATUS} 单表取,
+ * S-201② 那条律),于是这四句结构上够不着那道门。⇒ 它们由 `test/mcp-status-face-s481.test.ts` 的
+ * 「四句逐字节」那一格钉住(改一个字当场红)。把那道全局门扩到「常量表出站」形是另一台车。
+ */
+export declare function buildMcpProbeRateRefusal(): McpProbeRefusal;
+/**
+ * 在途帽满那一句(codex r1 [high] 的第二半)。**沿用** `limit.rate_exceeded` 而不新铸第五枚码:消费端的
+ * 分支与限速逐字相同(稍后再问),而拒码闭集每多一枚,按闭集写 `switch` 的消费端就多一次改。
+ * `retryAfterSec` 是**提示**不是承诺,而这一点必须说出来:每台的裁决有上界,但一个答完握手就卡住发送的
+ * 对端在引擎那边没有任何期限(core `docs/KNOWN-LIMITS.md`),所以「前面那次走查应该在这之内结束」是
+ * 常态下的话,不是最坏情况的保证。
+ */
+export declare function buildMcpProbeInflightRefusal(): McpProbeRefusal;
+/**
+ * 自带申报那一口上、core 的物化**拒了整份申报集**那一句(唯一的成文因由:两台在同一个命名空间前缀下挂载,
+ * 在任何传输被触碰**之前**就被拒)。
+ *
+ * 异源复核 [medium]:修前这一形在两条口上都被抛给分派器尾 ⇒ `500 internal.error`。可自带申报那一口的申报
+ * 是**调用方**写的,把它答成 500 是把调用方的错说成这台机器故障;中心申报那一口反过来 —— 那是部署方写的,
+ * 5xx 才是对的方向。⇒ 一条规则:**谁写的申报,谁的错**。
+ *
+ * 🔴 **不回显因由**:那句话来自申报集本身,可能带调用方的内情(名字、地址形)。调用方手里有自己的体,
+ * 点名「两台撞了命名空间」就够他自己找;原文留在那一层的日志里。
+ */
+export declare function buildMcpProbeDeclarationRefusal(): McpProbeRefusal;
+//# sourceMappingURL=mcp-probe.d.ts.map