@sema-agent/server 7.98.0 → 7.100.0

package/dist/plugins/checkpoint-store-sql.js

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 import { APPROVAL_GATE_KINDS_SQL_IN } from "../tool-approval.js";
 import { CheckpointError, MAX_RULE_TEXT_CHARS, validatePendingSteer, appendPendingSteer, checkpointVersionOf, winnerFromOutcome, summarizeCheckpoint, MAX_SUPPORTED_CHECKPOINT_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
 import { redactDeep, redactSecrets } from "../trace/redact.js";
-import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, RuleOfferRawSchema, backfillLegacyBatchMemberKind, screenUncoveredDetailSeat } from "../approval-card.js";
+import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, RuleOfferRawSchema, backfillLegacyBatchMemberKind, parkRowFacts, screenUncoveredDetailSeat } from "../approval-card.js";
 import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readJsonArrayColumn, readJsonObjectColumn, readNonNullJsonValueColumn, } from "./sql-json-column.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
@@ -168,6 +168,21 @@ function readRiskDescriptorCell(cell) {
         return null;
     }
 }
+function readParkRowFactsCell(cell) {
+    let pendingAction;
+    try {
+        pendingAction = decodeNullableJsonColumn(cell, readPendingActionMemberBody, "checkpoint.checkpoint $.pendingAction (operator queue row)");
+    }
+    catch (e) {
+        if (!isJsonColumnBodyProblem(e))
+            throw e;
+        recordFailOpen("server.approvals.park-row-blob-unreadable");
+        return {};
+    }
+    return parkRowFacts(pendingAction);
+}
+const PARK_ROW_PENDING_ACTION = { key: "pendingAction", as: "pending_action" };
+const readPendingActionMemberBody = createObjectColumnReader();
 export function boundedToolInput(args) {
     if (args === undefined)
         return null;
@@ -516,7 +531,8 @@ export class SqlCheckpointStore {
     async listPending(scope) {
         const d = this.db.dialect;
         const base = `SELECT c.session_id, c.scope, c.tool_name, c.tool_call_id, ${jsonColumnText(d, "tool_input")}, c.bound_input_hash, ` +
-            `${jsonColumnText(d, "risk_descriptor")}, ${jsonColumnText(d, "rule_suggestions")}, c.has_bidi_controls, c.created_at_ms, c.deadline, c.gate_kind, ta.task_id ` +
+            `${jsonColumnText(d, "risk_descriptor")}, ${jsonColumnText(d, "rule_suggestions")}, c.has_bidi_controls, c.created_at_ms, c.deadline, c.gate_kind, ta.task_id, ` +
+            `${jsonColumnText(d, "checkpoint", PARK_ROW_PENDING_ACTION)} ` +
             "FROM checkpoint c LEFT JOIN task_active ta ON ta.session_id = c.session_id WHERE c.status='pending'";
         const { rows } = scope
             ? await this.db.query(`${base}${this.q(" AND c.scope=?", " AND c.scope=$1")} ORDER BY c.created_at_ms ASC`, [scope])
@@ -543,6 +559,7 @@ export class SqlCheckpointStore {
                 ...(ruleOffers !== undefined ? { ruleOffers } : {}),
                 ...(Number(r.has_bidi_controls) === 1 ? { hasBidiControls: true } : {}),
                 ...(contentKindOf(toolName) !== undefined ? { contentKind: "content_ask" } : {}),
+                ...readParkRowFactsCell(r[PARK_ROW_PENDING_ACTION.as]),
             };
         });
         return out.sort((a, b) => (b.riskDescriptor?.severity ?? 0) - (a.riskDescriptor?.severity ?? 0) || a.createdAt - b.createdAt);

package/dist/plugins/local-checkpoint-store.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { ASK_USER_QUESTION_TOOL_NAME, contentKindOf } from "../approval-content-kind.js";
+import { parkRowFacts } from "../approval-card.js";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, unlinkSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
@@ -184,6 +185,7 @@ export class LocalCheckpointStore {
                 })(),
                 ...(pa?.hasBidiControls === true ? { hasBidiControls: true } : {}),
                 ...(contentKindOf(pa?.toolName ?? null) !== undefined ? { contentKind: "content_ask" } : {}),
+                ...parkRowFacts(cp.pendingAction),
             });
         }
         return rows.sort((a, b) => (b.riskDescriptor?.severity ?? 0) - (a.riskDescriptor?.severity ?? 0) || a.createdAt - b.createdAt);

package/dist/plugins/mailbox-store-sql.d.ts

@@ -12,8 +12,10 @@
  *     2026-07-25)起不再与 drop 同句**:reap 是收件人活着时的龄扫,**清箱保高水位**(删消息、清租约、盒行与
  *     next_seq 留着)——本文件 2026-09-03(车BF,codex r1 [high])才跟上;此前 reap 删盒行 ⇒ 下一条 append 从 1
  *     重铸,陈旧 ack 可删掉一条没人见过的新消息。跨进程试剂盒明钉此条。
- *  3. **ack 无 owner 守卫**(信任 claim 赢者链):`seq <= upToSeq` 删行;lease 的 `maxSeq <= upToSeq`
- *     时顺带清 lease(全量 ack = 释放)。
+ *  3. **ack 带 owner 围栏**(MB1,core 1.452 起;原「无守卫、信任 claim 赢者链」已被推翻):当前持租者才删
+ *     `seq <= upToSeq` 的行;lease 的 `maxSeq <= upToSeq` 时顺带清 lease(全量 ack = 释放)。**围栏的判决报出来**
+ *     (core 7.30.0 #1036,S-616):放行 ⇒ `{ acked: true }`(删 0 行也是 true —— 契约是「围栏放行」不是「删了几行」),
+ *     盒不在 / 无人持租 / 非持租者 ⇒ `{ acked: false }`;逐格与 core `InMemoryMailboxStore.ack` 同答。
  *  4. **lease 过期判 = 严格 `expiresAt > now` 才挡**;`releaseLease` 只在 owner 匹配时清。
  *  5. `peekCount` 含已 lease 消息(可见性 ≠ lease 态);空盒 claim = null(box 行在而消息 0 也 null)。
  *  6. **reap = SQL 全量真扫**(core File 实现只扫已加载盒 = 进程内 backstop,[ref] 确认 SQL 是全量
@@ -44,7 +46,7 @@
  */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import type { MailboxAppendMessage, MailboxLease, MailboxStore } from "@sema-agent/core";
+import type { MailboxAckResult, MailboxAppendMessage, MailboxLease, MailboxStore } from "@sema-agent/core";
 import { type IndexSpec } from "./ensure-index.js";
 import type { MailboxRecipientLifecycle, MailboxRecipientTombstone } from "./mailbox-recipient-lifecycle.js";
 export declare const MAILBOX_TABLE = "mailbox";
@@ -82,7 +84,7 @@ export declare class TiDBMailboxStore implements MailboxStore, MailboxRecipientL
     private tx;
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
-    ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<void>;
+    ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
     peekCount(scope: string, handle: string): Promise<number>;
     drop(scope: string, handle: string): Promise<void>;
@@ -108,7 +110,7 @@ export declare class PgMailboxStore implements MailboxStore, MailboxRecipientLif
     private assertIdentity;
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
-    ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<void>;
+    ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
     peekCount(scope: string, handle: string): Promise<number>;
     drop(scope: string, handle: string): Promise<void>;

package/dist/plugins/mailbox-store-sql.js

@@ -263,13 +263,14 @@ export class TiDBMailboxStore {
         });
     }
     async ack(scope, handle, owner, upToSeq) {
-        await this.tx(async (c) => {
+        return this.tx(async (c) => {
             const [rows] = (await c.query(`SELECT lease_owner FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]));
             if (rows.length === 0 || rows[0].lease_owner == null || bufToStr(rows[0].lease_owner) !== owner)
-                return;
+                return { acked: false };
             await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? AND seq <= ?`, [scope, handle, upToSeq]);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = NULL, lease_expires_at_ms = NULL, lease_max_seq = NULL
          WHERE scope_key = ? AND handle = ? AND lease_max_seq IS NOT NULL AND lease_max_seq <= ?`, [scope, handle, upToSeq]);
+            return { acked: true };
         });
     }
     async releaseLease(scope, handle, owner) {
@@ -410,13 +411,14 @@ export class PgMailboxStore {
         });
     }
     async ack(scope, handle, owner, upToSeq) {
-        await this.tx(async (c) => {
+        return this.tx(async (c) => {
             const r = (await c.query(`SELECT lease_owner FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2 FOR UPDATE`, [scope, handle]));
             if (r.rows.length === 0 || r.rows[0].lease_owner == null || bufToStr(r.rows[0].lease_owner) !== owner)
-                return;
+                return { acked: false };
             await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 AND seq <= $3`, [scope, handle, upToSeq]);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = NULL, lease_expires_at_ms = NULL, lease_max_seq = NULL
          WHERE scope_key = $1 AND handle = $2 AND lease_max_seq IS NOT NULL AND lease_max_seq <= $3`, [scope, handle, upToSeq]);
+            return { acked: true };
         });
     }
     async releaseLease(scope, handle, owner) {

package/dist/plugins/permission-rule-store-file.js

@@ -5,6 +5,7 @@ import { performance } from "node:perf_hooks";
 import { FileDurableRulePartitionProvider, AppendLog, ensureDir, readJsonlRecords, } from "@sema-agent/core";
 import { z } from "zod";
 import { buildRulePayloadHash } from "./permission-rule-store-sql.js";
+import { createSkippedRecordSink } from "../observability/corrupt-read-seat.js";
 import { EDITED_RULE_BREADTH_WARNING_CODES, RULE_APPROVAL_RECORD_SCHEMA, UNCOVERED_SEGMENT_REASONS } from "../permission-rule-vocab.js";
 import { RULE_BEHAVIORS } from "@sema-agent/core";
 const RuleScopeSchema = z.union([
@@ -140,7 +141,7 @@ export class FileRuleApprovalRecordStore {
         ensureDir(dir);
         const path = join(dir, "approvals.jsonl");
         this.gate = new CorruptionGate("permission-rule approval log", path, onError);
-        for (const raw of readJsonlRecords(path, (info) => this.gate.trip(info.reason))) {
+        for (const raw of readJsonlRecords(path, createSkippedRecordSink((info) => this.gate.trip(info.reason)))) {
             const parsed = ApprovalLineSchema.safeParse(raw);
             if (!parsed.success) {
                 const stale = StaleApprovalLineSchema.safeParse(raw);
@@ -209,7 +210,7 @@ export class FileRuleImportTicketStore {
         ensureDir(dir);
         const path = join(dir, "import-tickets.jsonl");
         this.gate = new CorruptionGate("permission-rule import-ticket log", path, onError);
-        for (const raw of readJsonlRecords(path, (info) => this.gate.trip(info.reason))) {
+        for (const raw of readJsonlRecords(path, createSkippedRecordSink((info) => this.gate.trip(info.reason)))) {
             const parsed = TicketLineSchema.safeParse(raw);
             if (!parsed.success) {
                 this.gate.trip(`a replayed record does not carry a readable shape: ${parsed.error.message}`);

package/dist/plugins/remote-env-host.d.ts

@@ -33,6 +33,8 @@ export interface HostEnvConfig {
     commandTimeoutMs?: number;
     /** Shell-child env policy (D1; mirrors core's `NodeExecutionEnv`). Default `"scrub"`: inherit the worker's
      *  `process.env` but DROP secret-pattern keys (core's `scrubSecretEnv` — `*_KEY`/`*_TOKEN`/`*_SECRET`/`*_PASSWORD`…)
+     *  AND every env name the server's config catalog types as `secret` (`server-secret-env.ts`; 7.99.0 F7 —
+     *  `SERVICE_AUTH_TOKENS` / `APPROVAL_HMAC_KEYS` slip the shape rule)
      *  so a model-driven shell can't `printenv DEEPSEEK_API_KEY` and exfiltrate orchestrator secrets — keeps PATH/HOME/
      *  locale/build (low breakage). `"all"` = inherit everything (explicit opt-out, trusted local dev). A `string[]` =
      *  strict allowlist. `env`/per-command `options.env` ALWAYS pass through verbatim. */
@@ -386,7 +388,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     private fsReady;
     /** Base env (process.env when inheriting) merged with the adapter's secret env, then per-command overrides win. */
     /** D1 secure default = `"scrub"`: inherit `process.env` minus secret-pattern keys (core's `scrubSecretEnv`, single
-     *  source of truth). `"all"` = full inherit (opt-out); a `string[]` = strict allowlist. Legacy `inheritProcessEnv`
+     *  source of the shape rule) minus the config catalog's `secret`-typed names (`scrubServerSecrets`, 7.99.0 F7). `"all"` = full inherit (opt-out); a `string[]` = strict allowlist. Legacy `inheritProcessEnv`
      *  maps `true`→`"all"` / `false`→`[]`. */
     private inheritMode;
     private mergeEnv;

package/dist/plugins/remote-env-host.js

@@ -9,8 +9,9 @@ import { armPipeDestroyGrace, numEnvOr, SYMLINK_CHAIN_MAX_HOPS } from "./remote-
 import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
 import { resolveHostShell, hostShell, spawnGroupOptions, killTreeHard, killTreeSoft, collapseWin32EnvKeys, adoptHostForegroundChild } from "./host-platform.js";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
-import { FileError, ExecutionError, RemoteExecutionError, scrubSecretEnv, RollingTailBuffer, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
+import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
 import { recordSecretEnvScrub } from "../observability/secret-env-scrub.js";
+import { scrubServerSecrets } from "../server-secret-env.js";
 import { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
 const PROVIDER = "host";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
@@ -1312,7 +1313,7 @@ export class RemoteHostExecutionEnv {
         }
         else {
             const findings = [];
-            base = scrubSecretEnv(process.env, findings);
+            base = scrubServerSecrets(process.env, findings);
             recordSecretEnvScrub("server.remote-env-host.inherit-scrub", findings);
         }
         if (this.cfg.env)

package/dist/plugins/sql-json-column.d.ts

@@ -46,11 +46,24 @@ import type { SqlDialect } from "./sql-driver.js";
  *
  * 🔴 **别名是产物的一部分,不是调用点的自由**:MySQL 协议下 `CAST(rules AS CHAR)` 的回报字段名是
  * `CAST(rules AS CHAR)` 而不是 `rules` —— 把别名留给调用点写,就等于给每一处读腿留一个「忘了写别名,
- * 行上于是没有这个键、读回恒 `undefined`」的静默洞。别名在这里一次钉死,行的键恒等于列名。
+ * 行上于是没有这个键、读回恒 `undefined`」的静默洞。别名在这里一次钉死,行的键恒等于列名(成员形
+ * {@link JsonColumnMember}:恒等于声明的小写别名)。
  *
  * 🔴 **`CAST` 不影响索引**:投影不在 `WHERE` 里;大体量列多一次文本拷贝,量级与现状同(驱动本来也解一次)。
  */
-export declare function jsonColumnText(dialect: SqlDialect, column: string): string;
+export declare function jsonColumnText(dialect: SqlDialect, column: string, member?: JsonColumnMember): string;
+/**
+ * 一列 JSON 的**一个顶层成员**(NP-3,7.100.0)—— 读腿只要文档里的一棵子树时用它,整只文档不出引擎。
+ *  · `key` = 成员名(裸标识符;进 MySQL 路径 `'$.<key>'` 与 PG 字面 `'<key>'`,所以只认裸标识符,不转义不猜);
+ *  · `as` = 行上的键(**小写**裸标识符:PG 把不带引号的别名折成小写,别的拼法会让两方言的行键不同)。
+ * 产物仍是**文本**(同一条「按文本投影、恰好解一次」),成员缺席 / 文档不是对象 ⇒ SQL NULL(两引擎同答),
+ * 所以读腿用 {@link decodeNullableJsonColumn}:NULL = 「这份文档没有这棵子树」,JSON `null` 字面 = 一个值(交形读者判)。
+ * 首个读者:`checkpoint-store-sql.ts` 的 `listPending`(运维队列 / `/v1/approvals/stream` 热读)只取 `pendingAction`。
+ */
+export interface JsonColumnMember {
+    readonly key: string;
+    readonly as: string;
+}
 /**
  * 同一只投影的**裸表达式**(不带别名)—— 给 `WHERE` / `UPDATE … WHERE` 这种**没有别名位**的地方用。
  *
@@ -68,7 +81,7 @@ export declare function jsonColumnText(dialect: SqlDialect, column: string): str
  * 子树,本函数的插值对它是一个不透明表达式。所以「误用进 SELECT 投影且没给别名」这一形没有机器门 ——
  * 误用的落点是真库上当场的 `SqlJsonColumnError("not-text")` 响亮抛(行上没有那个键 ⇒ `undefined`),不是静默。
  */
-export declare function jsonColumnTextExpr(dialect: SqlDialect, column: string): string;
+export declare function jsonColumnTextExpr(dialect: SqlDialect, column: string, memberKey?: string): string;
 /**
  * 一次读回失败的**种别**(店层码,**闭集**;运行期词表在这里,类型从它推导 —— 一张词表只有一个写者):
  *  · `not-text` —— 拿到的不是串 = **读腿漏了投影**,那是**码的问题不是数据的问题** ⇒ 响亮的程序错,

package/dist/plugins/sql-json-column.js

@@ -1,13 +1,24 @@
 import { z } from "zod";
 const COLUMN_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-export function jsonColumnText(dialect, column) {
-    return `${jsonColumnTextExpr(dialect, column)} AS ${column}`;
+export function jsonColumnText(dialect, column, member) {
+    if (member === undefined)
+        return `${jsonColumnTextExpr(dialect, column)} AS ${column}`;
+    if (!MEMBER_ALIAS_RE.test(member.as)) {
+        throw new Error(`jsonColumnText: member alias ${JSON.stringify(member.as)} must be a lower-case bare identifier — PostgreSQL folds unquoted aliases to lower case, so any other spelling would give the two dialects different row keys`);
+    }
+    return `${jsonColumnTextExpr(dialect, column, member.key)} AS ${member.as}`;
 }
-export function jsonColumnTextExpr(dialect, column) {
+const MEMBER_ALIAS_RE = /^[a-z_][a-z0-9_]*$/;
+export function jsonColumnTextExpr(dialect, column, memberKey) {
     if (!COLUMN_NAME_RE.test(column)) {
         throw new Error(`jsonColumnTextExpr: ${JSON.stringify(column)} is not a bare column identifier — refusing to splice it into SQL text`);
     }
-    return dialect === "pg" ? `${column}::text` : `CAST(${column} AS CHAR)`;
+    if (memberKey === undefined)
+        return dialect === "pg" ? `${column}::text` : `CAST(${column} AS CHAR)`;
+    if (!COLUMN_NAME_RE.test(memberKey)) {
+        throw new Error(`jsonColumnTextExpr: member ${JSON.stringify(memberKey)} is not a bare identifier — refusing to splice it into a JSON path`);
+    }
+    return dialect === "pg" ? `(${column}::jsonb -> '${memberKey}')::text` : `CAST(JSON_EXTRACT(${column}, '$.${memberKey}') AS CHAR)`;
 }
 export const SQL_JSON_COLUMN_PROBLEMS = ["not-text", "not-json", "malformed"];
 export class SqlJsonColumnError extends Error {

package/dist/plugins/web-search.d.ts

@@ -4,7 +4,9 @@
  * backend here is what makes `assembleFullBodyTools({ webSearch })` actually mount the WebSearch tool.
  *
  * Multi-provider, picked by `WEB_SEARCH_PROVIDER`:
- *   - `brave`   — Brave Web Search API (GET, `X-Subscription-Token` header)
+ *   - `brave`   — Brave Web Search API (GET, `X-Subscription-Token` header); with `WEB_SEARCH_ENDPOINT` set to a
+ *                 Brave-compatible gateway's full search URL (e.g. a self-hosted Nólë gateway, S-669) the same leg
+ *                 serves that backend — no new provider word, `capabilities.webSearch.backend` still reads `brave`
  *   - `tavily`  — Tavily Search API (POST, `Authorization: Bearer`, native include/exclude_domains)
  *   - `searxng` — a self-hosted SearXNG instance (GET `?format=json`, no auth)
  *
@@ -140,20 +142,6 @@ export declare function setWebSearchBadPayloadObserver(fn: ((provider: string) =
  * stays captured in this closure — it is never surfaced to the model or the tool args.
  */
 export declare function createWebSearchBackend(cfg: WebSearchBackendConfig): WebSearchBackend;
-/**
- * `WEB_SEARCH_SEARXNG_PARAMS` / `settings.webSearch.searxngParams` 的解析 —— SearXNG 实例侧参数
- * (`engines=` / `language=` 等)。
- *
- * 🔴 [ref] cli 逐串直证:3.18.0 我加了 `searxngParams` 字段和消费点,**却没开任何配置入口** ——
- * 两条门都没有位置填它,于是我在 [ref] 说的「这条是给你们的」是句空话。单测直接构造
- * `WebSearchBackendConfig` 传进去,**天然跳过了配置入口这一层**,于是「能力在」与「配得进」之间
- * 断开,而两边的绿都是真的。判据:**按消费端实际能填的那个入口验,不是按自己构造的对象验。**
- *
- * 形状:`k=v` 用 `;` 分隔(`engines=bing,duckduckgo;language=zh-CN`)——值里本来就常含逗号,
- * 所以分隔符取 `;` 而不是 `,`。整串解析不出任何一对 ⇒ **返回 undefined,键整个不铸**
- * (不产出空对象:空对象会让下游以为「配了但是空的」,与本仓「缺席就要缺席得干净」同源)。
- */
-export declare function parseSearxngParams(raw: unknown): Record<string, string> | undefined;
 /**
  * #81④ 探活门控 —— **默认 OFF**,显式开才探。
  *
@@ -165,14 +153,46 @@ export declare function parseSearxngParams(raw: unknown): Record<string, string>
  * 而猜错的方向是「凭空出网」。缺席要缺席得干净,含糊也一样。
  */
 export declare function shouldProbeWebSearchOnBoot(env?: NodeJS.ProcessEnv): boolean;
-/** Parse the deployment env into a backend config; `undefined` when no provider is set (⇒ WebSearch not assembled). */
+/** env 载体形错的机读码(拼法随 `config.<族>_invalid` 既有族,如 `config.model_provider_invalid`)。码按**规则**
+ *  命名、不按键名 —— 键名逐字在拒因里。 */
+export declare const WEB_SEARCH_CONFIG_INVALID_CODE = "config.web_search_invalid";
+/**
+ * `WEB_SEARCH_PROVIDER` 这一格的判官(provider 字段的 env 载体):缺席 / 词表外 ⇒ `undefined`(= 不装配,缺席语义)。
+ *
+ * 🔴 **读面只问这一只**(codex R1-F2):`config-catalog` 的 `WEB_SEARCH_PROVIDER` 行要的是「装配了哪只后端」这一格,
+ * 不是整份配置。首版它调的是 {@link webSearchConfigFromEnv} —— 那只对旁的 `WEB_SEARCH_*` 形错**抛**(拒启);嵌入式
+ * `createHttpServer` 不走 stage-07,形错的环境可以活在一只跑着的 server 里,于是读 provider 这一格就把整张目录打成
+ * 500。形错拒启归装配点(stage-07 / run-local 调整份解析),读面不替装配点再判一遍。
+ */
+export declare function webSearchProviderFromEnv(env?: NodeJS.ProcessEnv): WebSearchProvider | undefined;
+/**
+ * 部署 env ⇒ 后端配置。`WEB_SEARCH_PROVIDER` 缺席 / 词表外 ⇒ `undefined`(WebSearch 不装配,**不**读其余旋钮 ——
+ * 不消费的键不判);其余 `WEB_SEARCH_*` 任一形错 ⇒ **抛**(拒启,见 {@link envValue})。
+ */
 export declare function webSearchConfigFromEnv(env?: NodeJS.ProcessEnv): WebSearchBackendConfig | undefined;
 /**
- * Parse an UNTRUSTED per-request `body.settings.webSearch` (the user's shell settings — `{provider, apiKey?, endpoint?,
- * maxResults?}`) into a backend config. Returns `undefined` for a missing/invalid provider — NEVER throws, so a bad
- * per-request config falls back to the deployment-env backend rather than failing the task. 🔒 The CALLER gates this to
- * the single-user host lane (a per-request `endpoint`/`apiKey` is a capability config; on multi-tenant a tenant could
- * point `searxng` at an internal URL = SSRF, so multi-tenant uses ONLY the deployment-env backend — [ref] axis).
+ * 每请求 `body.settings.webSearch` 的判决 —— 受理面与装配点**同问这一只**:
+ *  · `absent`    —— 没带(或 `null`)⇒ 用部署后端;
+ *  · `honored`   —— 每个字段形对,且 `provider` 点名了一只本部署会说的后端 ⇒ 这次调用用它;
+ *  · `malformed` —— 任一字段形错 ⇒ 受理面 400 `request.field_invalid`(`issue` 逐字点名字段)。
+ * **`provider` 缺席或不在词表里也是形错**(S-199 主会话改判,codex 验修 V1 [high]):一段 `settings.webSearch` 就是
+ * 调用方在点名目的地(`endpoint` / `apiKey` 都挂在它点名的那只后端上),认不出就拒,不静默换成部署后端 —— 改判前
+ * 这一形回落部署后端,`{provider:"searx", endpoint:<私有地址>}` 的查询于是发到了部署配的后端。env 腿的同一只
+ * {@link isWebSearchProvider} 守卫对**部署**的词表外答「不装配」,那是部署自己的缺席,不是换别人的目的地。
+ * 规则集因此只剩三态,没有「形对但不采纳」这一臂。
+ *
+ * 🔒 采纳与否是**调用方**的事:装配点把整条腿闸在单用户车道(每请求 `endpoint`/`apiKey` 是能力配置;多租上一个
+ * 租户把 `searxng` 指向内网地址就是 SSRF,所以多租只认部署 env 的后端)。受理面的形判**不分车道**(与
+ * `settings.hooks` 同姿势:形在受理面判,采不采纳在装配点决定)。
  */
-export declare function webSearchConfigFromSettings(raw: unknown): WebSearchBackendConfig | undefined;
+export type RequestWebSearchVerdict = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "honored";
+    readonly config: WebSearchBackendConfig;
+} | {
+    readonly kind: "malformed";
+    readonly issue: string;
+};
+export declare function judgeRequestWebSearch(raw: unknown): RequestWebSearchVerdict;
 //# sourceMappingURL=web-search.d.ts.map

package/dist/plugins/web-search.js

@@ -1,8 +1,10 @@
 import { createSearxngSearchBackend } from "@sema-agent/core";
+import { isHierarchicalUrl } from "../trace/redact.js";
 export const WEB_SEARCH_PROVIDERS = ["brave", "tavily", "searxng"];
 function isWebSearchProvider(word) {
     return WEB_SEARCH_PROVIDERS.includes(word);
 }
+const providerWord = (raw) => raw.trim().toLowerCase();
 export function projectWebSearchCapability(provider) {
     return provider === undefined ? { backend: "none" } : { backend: provider };
 }
@@ -26,6 +28,10 @@ function withTimeout(signal, ms) {
 async function errorText(res) {
     return (await res.text().catch(() => "")).slice(0, 200);
 }
+async function httpFailure(provider, res) {
+    const body = await errorText(res);
+    return new Error(`${provider} search failed: HTTP ${res.status}${body ? ` — ${body}` : ""}`);
+}
 let onBadPayload;
 export function setWebSearchBadPayloadObserver(fn) {
     onBadPayload = fn;
@@ -62,7 +68,7 @@ async function braveSearch(fetchImpl, cfg, query, max, signal) {
     url.searchParams.set("count", String(Math.min(20, max)));
     const res = await fetchImpl(url, { headers: { Accept: "application/json", "X-Subscription-Token": cfg.apiKey }, signal });
     if (!res.ok)
-        throw new Error(`brave search failed (${res.status}): ${await errorText(res)}`);
+        throw await httpFailure("brave", res);
     const data = (await res.json());
     return normalize(data.web?.results, (r) => ({ title: r.title, url: r.url, snippet: r.description }), max, "brave");
 }
@@ -81,7 +87,7 @@ async function tavilySearch(fetchImpl, cfg, query, max, signal, opts) {
         signal,
     });
     if (!res.ok)
-        throw new Error(`tavily search failed (${res.status}): ${await errorText(res)}`);
+        throw await httpFailure("tavily", res);
     const data = (await res.json());
     return normalize(data.results, (r) => ({ title: r.title, url: r.url, snippet: r.content }), max, "tavily");
 }
@@ -132,64 +138,150 @@ export function createWebSearchBackend(cfg) {
     };
     return { search, maxResults };
 }
-export function parseSearxngParams(raw) {
-    if (typeof raw === "object" && raw !== null) {
-        const entries = Object.entries(raw);
-        if (entries.length === 0 || entries.some(([, v]) => typeof v !== "string"))
-            return undefined;
-        return Object.fromEntries(entries);
-    }
-    if (typeof raw !== "string")
-        return undefined;
-    const out = {};
-    for (const pair of raw.split(";")) {
-        const i = pair.indexOf("=");
-        if (i <= 0)
-            continue;
-        const k = pair.slice(0, i).trim();
-        const v = pair.slice(i + 1).trim();
-        if (k && v)
-            out[k] = v;
-    }
-    return Object.keys(out).length > 0 ? out : undefined;
-}
 export function shouldProbeWebSearchOnBoot(env = process.env) {
     const raw = env.WEB_SEARCH_PROBE_ON_BOOT?.trim().toLowerCase();
     return raw === "true" || raw === "1";
 }
-export function webSearchConfigFromEnv(env = process.env) {
-    const provider = env.WEB_SEARCH_PROVIDER?.trim().toLowerCase();
-    if (provider === undefined || !isWebSearchProvider(provider))
-        return undefined;
-    const searxngParams = parseSearxngParams(env.WEB_SEARCH_SEARXNG_PARAMS);
-    const maxRaw = Number(env.WEB_SEARCH_MAX_RESULTS ?? "");
-    const timeoutRaw = Number(env.WEB_SEARCH_TIMEOUT_MS ?? "");
+const ABSENT = { ok: true };
+const valueOf = (j) => (j.ok ? j.value : undefined);
+const isBlank = (s) => s.trim() === "";
+function judgeText(raw) {
+    if (raw === undefined || raw === null)
+        return ABSENT;
+    if (typeof raw !== "string")
+        return { ok: false, issue: "must be a string" };
+    return isBlank(raw) ? ABSENT : { ok: true, value: raw };
+}
+const ENDPOINT_FORM = "must be an absolute URL with a scheme and a host, such as https://search.example.com (a bare host or host:port is not one)";
+function judgeEndpoint(raw) {
+    if (raw === undefined || raw === null)
+        return ABSENT;
+    if (typeof raw !== "string")
+        return { ok: false, issue: ENDPOINT_FORM };
+    if (isBlank(raw))
+        return ABSENT;
+    return isHierarchicalUrl(raw) ? { ok: true, value: raw } : { ok: false, issue: ENDPOINT_FORM };
+}
+const COUNT_FORM = "must be a number ≥ 1";
+function judgeCount(raw) {
+    if (raw === undefined || raw === null)
+        return ABSENT;
+    return typeof raw === "number" && Number.isFinite(raw) && raw >= 1 ? { ok: true, value: Math.floor(raw) } : { ok: false, issue: COUNT_FORM };
+}
+function envNumber(raw) {
+    return raw === undefined || isBlank(raw) ? undefined : Number(raw.trim());
+}
+const SEARXNG_PARAM_NAME = /^[A-Za-z0-9_.-]+$/;
+const SEARXNG_PARAMS_FORM = 'must be an object of parameter name → non-empty string, or a "name=value;name=value" string';
+function judgeSearxngParams(raw) {
+    if (raw === undefined || raw === null)
+        return ABSENT;
+    const pairs = [];
+    if (typeof raw === "string") {
+        const segments = raw.split(";");
+        for (const [i, seg] of segments.entries()) {
+            if (isBlank(seg))
+                continue;
+            const eq = seg.indexOf("=");
+            if (eq < 0)
+                return { ok: false, issue: `${SEARXNG_PARAMS_FORM} — segment ${i + 1} has no "="` };
+            pairs.push([seg.slice(0, eq).trim(), seg.slice(eq + 1).trim()]);
+        }
+    }
+    else if (typeof raw === "object" && !Array.isArray(raw)) {
+        const entries = Object.entries(raw);
+        for (const [k, v] of entries) {
+            if (typeof v !== "string")
+                return { ok: false, issue: `${SEARXNG_PARAMS_FORM} — the value of ${JSON.stringify(k)} is not a string` };
+            pairs.push([k, v.trim()]);
+        }
+    }
+    else {
+        return { ok: false, issue: `${SEARXNG_PARAMS_FORM} — got ${Array.isArray(raw) ? "an array" : `a ${typeof raw}`}` };
+    }
+    const seen = new Set();
+    for (const [k, v] of pairs) {
+        if (!SEARXNG_PARAM_NAME.test(k))
+            return { ok: false, issue: `${SEARXNG_PARAMS_FORM} — ${JSON.stringify(k)} is not a parameter name (letters, digits, "_", "-", ".")` };
+        if (v === "")
+            return { ok: false, issue: `${SEARXNG_PARAMS_FORM} — ${k} has an empty value` };
+        if (seen.has(k))
+            return { ok: false, issue: `${SEARXNG_PARAMS_FORM} — ${k} is given more than once` };
+        seen.add(k);
+    }
+    return pairs.length === 0 ? ABSENT : { ok: true, value: Object.fromEntries(pairs) };
+}
+function assembleBackendConfig(provider, f) {
     return {
         provider,
-        ...(env.WEB_SEARCH_API_KEY ? { apiKey: env.WEB_SEARCH_API_KEY } : {}),
-        ...(env.WEB_SEARCH_ENDPOINT ? { endpoint: env.WEB_SEARCH_ENDPOINT } : {}),
-        ...(searxngParams ? { searxngParams } : {}),
-        ...(Number.isFinite(maxRaw) && maxRaw > 0 ? { maxResults: Math.floor(maxRaw) } : {}),
-        ...(Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? { timeoutMs: Math.floor(timeoutRaw) } : {}),
+        ...(f.apiKey !== undefined ? { apiKey: f.apiKey } : {}),
+        ...(f.endpoint !== undefined ? { endpoint: f.endpoint } : {}),
+        ...(f.searxngParams !== undefined ? { searxngParams: f.searxngParams } : {}),
+        ...(f.maxResults !== undefined ? { maxResults: f.maxResults } : {}),
+        ...(f.timeoutMs !== undefined ? { timeoutMs: f.timeoutMs } : {}),
     };
 }
-export function webSearchConfigFromSettings(raw) {
-    if (!raw || typeof raw !== "object")
+export const WEB_SEARCH_CONFIG_INVALID_CODE = "config.web_search_invalid";
+function envValue(key, j) {
+    if (!j.ok) {
+        throw new Error(`env ${key} ${j.issue} [${WEB_SEARCH_CONFIG_INVALID_CODE}] — fix it or unset it (an empty value counts as unset). ` +
+            "WebSearch reads its WEB_SEARCH_* knobs only when WEB_SEARCH_PROVIDER names a backend, and every knob it reads must be well-formed: " +
+            "a malformed value used to be absorbed silently (garbage parameters sent to the search instance, or a quiet fall-back to a default nobody chose).");
+    }
+    return j.value;
+}
+export function webSearchProviderFromEnv(env = process.env) {
+    const raw = env.WEB_SEARCH_PROVIDER;
+    const word = raw === undefined ? undefined : providerWord(raw);
+    return word !== undefined && isWebSearchProvider(word) ? word : undefined;
+}
+export function webSearchConfigFromEnv(env = process.env) {
+    const provider = webSearchProviderFromEnv(env);
+    if (provider === undefined)
         return undefined;
+    return assembleBackendConfig(provider, {
+        apiKey: envValue("WEB_SEARCH_API_KEY", judgeText(env.WEB_SEARCH_API_KEY)),
+        endpoint: envValue("WEB_SEARCH_ENDPOINT", judgeEndpoint(env.WEB_SEARCH_ENDPOINT)),
+        searxngParams: envValue("WEB_SEARCH_SEARXNG_PARAMS", judgeSearxngParams(env.WEB_SEARCH_SEARXNG_PARAMS)),
+        maxResults: envValue("WEB_SEARCH_MAX_RESULTS", judgeCount(envNumber(env.WEB_SEARCH_MAX_RESULTS))),
+        timeoutMs: envValue("WEB_SEARCH_TIMEOUT_MS", judgeCount(envNumber(env.WEB_SEARCH_TIMEOUT_MS))),
+    });
+}
+const SETTINGS_WEB_SEARCH_FORM = "settings.webSearch must be an object { provider, apiKey?, endpoint?, searxngParams?, maxResults? }";
+function judgeRequestProvider(raw) {
+    const got = raw === undefined || raw === null ? "it is missing" : typeof raw === "string" ? `got ${JSON.stringify(raw.slice(0, 40))}` : `got a ${Array.isArray(raw) ? "array" : typeof raw}`;
+    const word = typeof raw === "string" ? providerWord(raw) : undefined;
+    return word !== undefined && isWebSearchProvider(word)
+        ? { ok: true, value: word }
+        : { ok: false, issue: `must name one of ${WEB_SEARCH_PROVIDERS.join(" | ")} (${got}) — it names where this request's searches go, so an unknown or missing provider is refused rather than replaced by this deployment's own backend` };
+}
+export function judgeRequestWebSearch(raw) {
+    if (raw === undefined || raw === null)
+        return { kind: "absent" };
+    if (typeof raw !== "object" || Array.isArray(raw))
+        return { kind: "malformed", issue: SETTINGS_WEB_SEARCH_FORM };
     const s = raw;
-    const provider = typeof s.provider === "string" ? s.provider.trim().toLowerCase() : "";
-    if (!isWebSearchProvider(provider))
-        return undefined;
-    const max = typeof s.maxResults === "number" && Number.isFinite(s.maxResults) && s.maxResults > 0 ? Math.floor(s.maxResults) : undefined;
+    const provider = judgeRequestProvider(s.provider);
+    if (!provider.ok)
+        return { kind: "malformed", issue: `settings.webSearch.provider ${provider.issue}` };
+    const fields = {
+        apiKey: judgeText(s.apiKey),
+        endpoint: judgeEndpoint(s.endpoint),
+        searxngParams: judgeSearxngParams(s.searxngParams),
+        maxResults: judgeCount(s.maxResults),
+    };
+    for (const [field, j] of Object.entries(fields)) {
+        if (!j.ok)
+            return { kind: "malformed", issue: `settings.webSearch.${field} ${j.issue}` };
+    }
     return {
-        provider,
-        ...(typeof s.apiKey === "string" && s.apiKey ? { apiKey: s.apiKey } : {}),
-        ...(typeof s.endpoint === "string" && s.endpoint ? { endpoint: s.endpoint } : {}),
-        ...(() => {
-            const p = parseSearxngParams(s.searxngParams);
-            return p ? { searxngParams: p } : {};
-        })(),
-        ...(max ? { maxResults: max } : {}),
+        kind: "honored",
+        config: assembleBackendConfig(provider.value, {
+            apiKey: valueOf(fields.apiKey),
+            endpoint: valueOf(fields.endpoint),
+            searxngParams: valueOf(fields.searxngParams),
+            maxResults: valueOf(fields.maxResults),
+        }),
     };
 }
 //# sourceMappingURL=web-search.js.map