@sema-agent/server 7.55.0 → 7.57.0

package/dist/trace/redact.d.ts

@@ -1,17 +1,28 @@
-export declare function setRedactionObserver(fn: ((patternLabel: string, count: number) => void) | undefined): void;
-/**
- * `opts.observe: false` = **照常脱敏,但这一遍不计数**(合并码重扫)。
- *
- * 为什么需要它:本函数对自己的输出**值幂等、计数不幂等** —— URL-userinfo 与 JSON 秘密字段两条 pattern
- * 会命中自己已经替换过的输出并再计一次。于是任何**重扫已脱敏文本**的读路径(耐久待批队列的回读腿,
- * `/v1/approvals/stream` 每 3s 一拍)都会持续给 `redactions_applied_total` 加数,把那个用来识别
- * 「过度脱敏 / pattern 从不触发」的指标灌成不可读。
+/** 测试可见:扫描器 indexOf 实际扫过的字节数(摊还线性 ⇒ ≤ 常数 × 输入长)。 */
+export declare function ppkScanBytesForTest(): number;
+export declare function resetPpkScanBytesForTest(): void;
+/** Redact unambiguous secret formats from reasoning/CoT before it is persisted to the durable trace log. */
+/** S24 (SILENT-FALLBACK P1): optional redaction observer — rewrites previously had zero fingerprint, so
+ *  over-redaction (mangling legit content) and under-redaction (a pattern that never fires) were both
+ *  invisible. main.ts wires this to `redactions_applied_total{pattern}`. Hot path: the observer only runs
+ *  when a pattern actually matched; the label is derived once per pattern at module load. */
+/** [ref]:第三参 `meta.arm` = 命中的是哪一组臂。加参而不是改参 —— 只读两参的既有观察者原样可用
+ *  (TS 允许少形参),main.ts 把它铺成 `redactions_applied_total{pattern,arm}` 的第二个维度。
  *
- * 🔴 关的是**计数**,不是脱敏:重扫这一遍仍是纵深防御(手改过的行、未来某条写路径漏了脱敏,读面照样
- * 兜住)—— 少脱一次的代价是把凭证投上跨租户可见的运维队列,那条永远不能省。
- */
+ *  🔴 **词义如实**(codex r1 [medium] 三,采纳):这一维说的是「命中的是**哪一条臂**」,**不是**
+ *  「这段文本真的被上游截过」—— server 收到的是纯字节,core 的 `clip()` 是 `slice(0, 80)` **不留标记**
+ *  (亲读 `@sema-agent/core/dist/agents/subagent-steps.js:9-11`),截过与天生就短在 wire 上不可区分。
+ *  所以一个 `arm="fragment"` 计数可能来自残片,也可能来自一个恰好落在阈值之上的 look-alike;
+ *  core [ref] 落地后这一支**趋零是证据、不归零不是证明**。别把它当截断事实的度量用。 */
+export type RedactionArm = "full" | "fragment";
+export interface RedactionHitMeta {
+    /** `"fragment"` = {@link FRAGMENT_SECRET_PATTERNS} 里的前缀残片臂;`"full"` = 完整臂。闭集两词。 */
+    arm: RedactionArm;
+}
+export declare function setRedactionObserver(fn: ((patternLabel: string, count: number, meta: RedactionHitMeta) => void) | undefined): void;
 export declare function redactSecrets(text: string, opts?: {
     observe?: boolean;
+    json?: boolean;
 }): string;
 /**
  * 🔴 环 + 深度预算(2026-07-25 补)。原实现是纯递归、**既不记已访问节点也不限深度**,而它的调用位置是