@sema-agent/server 7.79.0 → 7.79.2

package/dist/file-history-disclosure.d.ts

@@ -0,0 +1,53 @@
+/**
+ * S-157④ —— SQL file-history 店的 **typed 永久失败**披露座:散文一个铸点 + 机器面一只 sink。
+ *
+ * ## 病(基线 v7.79.0 逐行亲核 + 亲跑)
+ * `plugins/blob-backend.ts:55` 的 `BlobTooLargeError` 带 typed 判别码 `blob_too_large_for_sql`,头注
+ * 原话「绝不能与 transient 写失败混在一类(那类是可重试的 502;这类重试永远不会成功)」。可它一旦被
+ * `plugins/file-history-store-sql.ts` 的任何一条 `catch` 折进 `FileHistoryResult.error.message`,判别码
+ * 就只剩散文,**机器一位都读不到**。两条腿各自的后果:
+ *
+ * · **snapshot(边界捕获)腿**:引擎把失败包成一句散文交给 `RunnerDeps.onError({phase:"rewind"})`
+ *   (core 7.20.0 `dist/core/runner/prepare-file-history.js:269`/`:275`),服务那条臂从文本里抠**第一个**
+ *   括号词当 metric label —— 而第一个括号词恒是引擎自己的闭集码。实测:「这个文件永远存不进这口店」
+ *   与「连接被重置」在 `rewind_snapshot_failed_total` 上**同形** `code="snapshot_failed"`。
+ * · **trackEdit(首触备份)腿**:本服务用引擎默认的 `onTrackFailure:"refuse"`(`boot/runner-deps.ts` 亲读),
+ *   那条路 **完全不走 onError** —— 引擎把 `(track_failed: <本店 message>)` 念给模型,末句是
+ *   「Retry when the file-history store is healthy.」(`prepare-file-history.js:154`)。对这枚码那是永远
+ *   不会到来的一天,而**运维面一个计数都没有**:这条腿今天在遥测上完全不可见。
+ *
+ * ## 修法(源头留痕,不走文本通道)
+ * · **散文面**({@link discloseCaughtFailure} 的返回值):把 caught error 的 typed `code` 写成一个括号词
+ *   前置到它自己的 message 前 —— **不 `instanceof` 单挑任何一个类**(身上有字符串 `code` 就折),该店
+ *   11 处折点全部改走这一只函数。人与模型因此看得到「这是哪一类失败」。
+ * · **机器面**(同一只函数的副作用):码取自 typed 错**对象**、对闭集词表判定,**绝不从散文里抠**。
+ *   🔴 这一条是 codex R1-[high] 验真后的定形:文本通道**天然可伪造** —— 一个名叫
+ *   `(blob_too_large_for_sql).txt` 的文件读不出来时,它的路径就在 `snapshot_failed` 的散文里,任何
+ *   「从散文里取在册括号词」的读法都会把它当成一枚永久码(继而抑制掉真故障的告警)。闭集只约束基数,
+ *   不能证明来源。所以机读判定搬回**唯一知道真相的那一层**=铸错的地方,`rewind` 臂的读法一字不动。
+ * · 留痕三件套与 `observability/fail-open.ts` / `observability/secret-env-scrub.ts` 同律:**计数逐次**
+ *   (`file_history_permanent_failure_total{code}`)、**每进程每码一条 warn**(第二条起零新增内容,而
+ *   20G 树的用户每 turn 撞一次)、装配前累计的次数在 install 时补进 metrics。
+ */
+import type { Logger } from "./observability/logger.js";
+import type { Metrics } from "./observability/metrics.js";
+interface Sink {
+    logger?: Logger;
+    metrics?: Metrics;
+}
+/**
+ * 把一个 caught error 折进店侧散文,**并**在它是一枚 typed 永久失败时留痕。
+ *
+ * 返回值 = 散文形:带 typed `code` 的前缀一个括号词(`(blob_too_large_for_sql) blob of … exceeds …`),
+ * 不带的**逐字**是原 message(transient 失败的文案因此与本批之前一字不差)。
+ * 副作用 = 机器形:码取自错误对象,逐次计数 + 每进程每码一条 warn。观测绝不抛。
+ */
+export declare function discloseCaughtFailure(err: unknown): string;
+/** 装配层把 logger/metrics 接上(main.ts,与 `installFailOpenRecorder` 同一处)。 */
+export declare function installFileHistoryFailureRecorder(deps: Sink): void;
+/** 本进程逐码累计(测试/诊断读面)。 */
+export declare function fileHistoryPermanentFailureCounts(): ReadonlyMap<string, number>;
+/** 测试用重置(进程级状态在同一个 vitest worker 里跨用例存活)。 */
+export declare function resetFileHistoryFailureRecorderForTest(deps?: Sink): void;
+export {};
+//# sourceMappingURL=file-history-disclosure.d.ts.map

package/dist/file-history-disclosure.js

@@ -0,0 +1,89 @@
+const PERMANENT_STORE_FAILURE_CODES = {
+    blob_too_large_for_sql: {
+        note: "a blob is larger than this deployment's SQL snapshot-blob cap — the same file will fail every turn until the deployment changes",
+        knobs: "MINIO_ENDPOINT/MINIO_ACCESS_KEY/MINIO_SECRET_KEY (object storage) or SNAPSHOT_BLOB_SQL_MAX_BYTES (raise the cap)",
+    },
+};
+const PERMANENT_FAILURE_COUNTER = "file_history_permanent_failure_total";
+const PERMANENT_FAILURE_HELP = "file-history store failures whose typed code means retrying can NEVER succeed (the deployment must change), by code. " +
+    "Covers BOTH legs — the rewind boundary capture AND the first-touch trackEdit refusal, which the engine answers to the model " +
+    "without ever calling onError, so it appears in no other metric. Non-zero = go read the paired one-shot warn for the knobs.";
+let sink = {};
+let counts = new Map();
+let pushed = new Map();
+let warned = new Set();
+let pendingWarn = new Map();
+function isPermanentCode(code) {
+    return Object.prototype.hasOwnProperty.call(PERMANENT_STORE_FAILURE_CODES, code);
+}
+function drainToMetrics() {
+    const m = sink.metrics;
+    if (m === undefined)
+        return;
+    for (const [code, total] of counts) {
+        const already = pushed.get(code) ?? 0;
+        if (total > already) {
+            m.inc(PERMANENT_FAILURE_COUNTER, { code }, total - already);
+            pushed.set(code, total);
+        }
+    }
+}
+export function discloseCaughtFailure(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const code = err?.code;
+    if (typeof code !== "string" || code === "")
+        return message;
+    if (isPermanentCode(code))
+        recordPermanent(code, message);
+    return `(${code}) ${message}`;
+}
+function safely(record) {
+    try {
+        record();
+    }
+    catch {
+    }
+}
+function recordPermanent(code, message) {
+    safely(() => {
+        counts.set(code, (counts.get(code) ?? 0) + 1);
+        drainToMetrics();
+        if (!warned.has(code))
+            emitFirstWarn(code, message);
+    });
+}
+function emitFirstWarn(code, message) {
+    if (!pendingWarn.has(code))
+        pendingWarn.set(code, message);
+    const logger = sink.logger;
+    if (logger === undefined)
+        return;
+    logger.warn("file_history_permanent_failure", {
+        code,
+        note: PERMANENT_STORE_FAILURE_CODES[code].note,
+        knobs: PERMANENT_STORE_FAILURE_CODES[code].knobs,
+        info: pendingWarn.get(code) ?? message,
+        once: "每进程每码一条;计数逐次,读 " + PERMANENT_FAILURE_COUNTER,
+    });
+    warned.add(code);
+    pendingWarn.delete(code);
+}
+export function installFileHistoryFailureRecorder(deps) {
+    sink = { ...deps };
+    deps.metrics?.counter(PERMANENT_FAILURE_COUNTER, PERMANENT_FAILURE_HELP);
+    drainToMetrics();
+    for (const [code, message] of [...pendingWarn])
+        safely(() => emitFirstWarn(code, message));
+}
+export function fileHistoryPermanentFailureCounts() {
+    return new Map(counts);
+}
+export function resetFileHistoryFailureRecorderForTest(deps = {}) {
+    counts = new Map();
+    pushed = new Map();
+    warned = new Set();
+    pendingWarn = new Map();
+    sink = { ...deps };
+    deps.metrics?.counter(PERMANENT_FAILURE_COUNTER, PERMANENT_FAILURE_HELP);
+}
+//# sourceMappingURL=file-history-disclosure.js.map

package/dist/http/admission.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 提交准入(S-147 切片:`http/server.ts` 的 `prepareSpec` 与它的模块级校验词表逐字搬家,正文一字未改)。
+ * 读体 → 验型 → 授权 → 建 spec 的**唯一**一条链;tasks / runs / A2A 三个提交面共用它(抄一份 = 抄一份会漂的 400)。
+ * ctx 字段 3 只(`deps` / `readJson` / `runnerFor`),机器算(closure-free-vars)与手抄一致。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { TaskRequestBody } from "./wire-types.js";
+import { HttpError } from "../security.js";
+import type { PreparedTaskSubmission, RouteHelpers } from "./route-ctx.js";
+import type { FlatServiceDeps } from "./server.js";
+/** = core `SKILL_CONTENT_MAX_CHARS`(1MB 加载门,core 1.293 起 invoke 全文零截断、超 1MB 整拒;常量在
+ *  dist/core/runner/synthetic-tools.js:84,未从 core 包根导出,故钉本地孪生+本出处注记)。修7 曾对齐旧
+ *  20k 截断门([ref] 飞轮考据:20k 是压缩保留区口径,invoke 时刻用错),core 1.293 撤门后本门跟随回收
+ *  ([ref]① 收口)——HTTP 面与引擎加载门同值,超限 400 fail-loud 而非引擎侧整拒后难诊断。
+ *
+ *  🔴 **这是技能面**唯一**剩下的尺寸门,而且它不是超集帽**:引擎在装配期对超 1 MiB 的技能本就整拒
+ *  (config 阶段错误),门上先答只是把同一个判决搬到调用方看得懂的地方。[ref] 退役的三条帽
+ *  (条数 / description / name 长度)都没有这个性质——它们是本仓自造的、CC 与引擎都没有的门。 */
+export declare const MAX_SKILL_CONTENT_CHARS = 1048576;
+export declare const MAX_SYSTEM_PROMPT_CHARS = 16384;
+/** Cap on a request's `outputSchema` (JSON-serialized) — an uncapped schema bloats the prompt + the per-turn
+ *  validation cost. 32KB comfortably holds a rich nested schema while bounding the abuse surface. */
+export declare const MAX_OUTPUT_SCHEMA_CHARS = 32768;
+/**
+ * Validate `body.skills` —— **形**校验 + 一条引擎孪生门。返回错误串(→ 400)或 null。
+ *
+ * 🔴 **[ref](7.77.0,硬 BREAKING;零别名零双读)**:此前这里有三条本仓自造的拒绝臂,全部退役 ——
+ *  · `at most 10 skills per request`(条数帽);
+ *  · `skill.description must be a string of at most 1024 characters`(描述长度帽);
+ *  · `skill.name must be a non-empty string of at most 64 characters` 里的 **长度**那一半。
+ *
+ * 退役的判据是**上游两侧都没有同形门**:CC 2.1.259 的技能清单渲染(`cli259.js:23195` 的预算算法)
+ * 在超预算时把**描述裁短**、再不够就退成 name-only,**从不**因为条数多或描述长而拒掉一条技能;
+ * 它的 `Ir()` 名字校验也只判非空 / 无配对代理 / 无首尾空白 / 无括号逗号控制字符,没有长度帽。
+ * 引擎侧同理:唯一整拒的是 1 MiB 的单技能加载门。于是那三条帽是「装了 11 个技能就 400」这种
+ * 纯本仓面的伤——收益是零(预算由渲染侧按字节兜),代价是用户装不进自己的技能库。
+ *
+ * **补偿**(三问的第三问):`settings.skillListingBudgetFraction` / `settings.skillListingMaxDescChars`
+ * 两个旋钮直达引擎的渲染预算(per-turn 成本的真属主)。
+ * ⚠️ **fraction 是**单向**的**:引擎的预算 = `min(窗口 × fraction, 8 000 字节)`,8 000 是**投递车道的结构
+ * 上限**(清单帧与同 turn 的其它附件共用一份完整送达额度)⇒ **调低生效、调高被夹**;调高唯一的用处是让
+ * 一个声明窗口小于 200 000 token 的模型把清单预算拿回大窗口的水平。别把这句读成「调用方可以随便加大」。
+ * 体积面照旧由**非技能专属**的 8 MiB 请求体上限兜住(`MAX_BODY`),那是一条一直都在的门。
+ *
+ * 🔴 **server 侧禁裁列表 / 禁截描述**:渲染归引擎(单一属主)。本函数只判「这一条技能的形能不能用」。
+ */
+export declare function validateUserSkills(skills: unknown): string | null;
+export declare function createAdmission(ctx: {
+    deps: FlatServiceDeps;
+    runnerFor: NonNullable<FlatServiceDeps["runnerFor"]>;
+} & Pick<RouteHelpers, "readJson">): {
+    prepareSpec: (req: IncomingMessage, res: ServerResponse, bodyIn?: TaskRequestBody, onTypedFailure?: (err: HttpError) => void, legFacts?: {
+        liveStream?: boolean;
+    }) => Promise<PreparedTaskSubmission | null>;
+};
+//# sourceMappingURL=admission.d.ts.map