@sema-agent/server 1.323.0 → 2.0.0

package/dist/plugins/tidb-workflow-run-store.js

@@ -1,2 +1,10 @@
+/**
+ * Thin re-export shim (design/158 A12 扇出): the TiDB `WorkflowRunStore`/`WorkflowCompletionInbox`/
+ * `WorkflowNotifyJournalStore` twins now live collapsed with their PG dialect siblings in the
+ * single-file dual-dialect `workflow-run-store-sql.ts`. Class names, ctor arity, and the exported
+ * `MAX_RUN_BLOB_BYTES` / `slimOversizeRun` / `InboxWarn` surface stay EXACTLY as they were — every
+ * consumer (store-backend.ts, the DB-integration + slim-oversize-run suites) imports from THIS path
+ * unchanged.
+ */
 export { MAX_RUN_BLOB_BYTES, slimOversizeRun, TiDBWorkflowRunStore, TiDBWorkflowCompletionInbox, TiDBWorkflowNotifyJournalStore, } from "./workflow-run-store-sql.js";
 //# sourceMappingURL=tidb-workflow-run-store.js.map

package/dist/plugins/tool-result-store-sql.d.ts

@@ -1,24 +1,82 @@
+/**
+ * Durable backing store for offloaded large tool results (core 1.47 offload / 1.49 durable contract) —
+ * SINGLE-FILE DUAL-DIALECT (design/158 A12 定型半场). ONE implementation, TWO dialects; the historical
+ * `TiDBToolResultStore` / `PgToolResultStore` class names survive as thin ctor subclasses so every consumer
+ * (store-backend.ts, the fake-pool unit suites, the real-DB integration suites) is untouched.
+ *
+ * Mirrors core's reference `TiDbToolResultStore` adapter. Without this, the Runner defaults to a
+ * task-scoped in-memory store: an async run that wakes on ANOTHER replica can't `read_tool_result` an
+ * offloaded result (the ref misses → the model is told it's unavailable; the preview still stands, so it
+ * degrades, never crashes). A durable store survives wake/resume across the stateless fleet.
+ *
+ * core namespaces the ref as `tr_<sessionId>_<toolCallId>` (1.49) → globally unique → usable directly as
+ * the PRIMARY KEY (no composite key needed). `put` is write-once (idempotent on replay/retry: a retry is
+ * a NEW toolCallId → new ref, so a given ref never changes content). Retention is anchored to a run's
+ * RECOVERABLE window via TTL (`reapOlderThan`): a resumable run may re-fetch an old ref after wake, but a
+ * completed run only needs the preview for audit/replay — so a TTL comfortably exceeding the run lifetime
+ * bounds storage without losing recoverable full-text.
+ *
+ * ── Dialect deltas, kept EXPLICIT ────────────────────────────────────────────────────────────────────
+ *   - `?` placeholders vs `$n`
+ *   - write-once insert = `INSERT IGNORE` vs `INSERT ... ON CONFLICT (ref) DO NOTHING`
+ *   - affectedRows vs rowCount (via SqlDriver)
+ *   - `SUBSTRING(content, ?, ?)` (1-indexed, comma form) vs the ANSI `SUBSTRING(content FROM $n::int FOR
+ *     $m::int)` positional form WITH explicit `::int` casts — node-pg binds bare params as text, and
+ *     `SUBSTRING(s FROM <text>)` is the POSIX-REGEX overload (it would treat $1 as a pattern); the cast
+ *     forces the positional integer overload. `CHAR_LENGTH` is ANSI and shared.
+ *   - content column: TiDB LONGTEXT vs PG TEXT (PG has no LONGTEXT; TEXT is unbounded), DATETIME(3) vs
+ *     TIMESTAMPTZ(3) — schema only (TiDB DDL in tidb-pool.ts; PG DDL self-contained below, exported for the
+ *     integration test + pg-pool.ts's central apply).
+ *   - `put`'s UTF-16 sanitize is a GENUINE algorithm divergence, not just SQL text — see the dialect branch
+ *     inline for why.
+ *   - ESCAPE-clause literal: TiDB spells `ESCAPE '\\\\'` (declares the backslash escape char explicitly —
+ *     under `sql_mode=NO_BACKSLASH_ESCAPES` `\` is NOT the LIKE escape char by default, so leaving it
+ *     implicit would silently stop escaping and let a crafted sessionId's `_`/`%` over-match OTHER
+ *     sessions' rows); PG spells `ESCAPE '\'` (its default escape char already, kept for lock-step intent
+ *     with the TiDB twin rather than out of necessity).
+ */
 import type { ToolResultStore, ToolResultSlice } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool, PoolClient as PgPoolClient } from "pg";
 import { type SqlDriver } from "./sql-driver.js";
+/** PG schema for the tool_result table — the PG translation of tidb-pool.ts's tool_result DDL
+ *  (LONGTEXT→TEXT, DATETIME(3)→TIMESTAMPTZ(3), inline KEY→separate CREATE INDEX). Disjoint from other stores'
+ *  tables, so a self-contained ensureSchema is safe (central pg-pool aggregation is done separately). */
 export declare const PG_TOOL_RESULT_SCHEMA: string[];
+/** Idempotent schema apply for the tool_result table (for the integration test to call). */
 export declare function ensureSchema(pool: PgPool | PgPoolClient): Promise<void>;
+/** Dual-dialect durable ToolResultStore. See the file header for the dialect-delta ledger. */
 export declare class SqlToolResultStore implements ToolResultStore {
     protected readonly db: SqlDriver;
     constructor(db: SqlDriver);
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     put(ref: string, content: string): Promise<void>;
     get(ref: string, opts?: {
         offset?: number;
         limit?: number;
     }): Promise<ToolResultSlice | undefined>;
+    /** TTL reap: delete results older than `cutoffMs`. Returns rows removed. */
     reapOlderThan(cutoffMs: number): Promise<number>;
+    /**
+     * E21 (§0.5 session delete) — purge offloaded tool results for one session. core namespaces every ref as
+     * `tr_<sessionId>_<toolCallId>`, so a `LIKE 'tr_<sessionId>_%'` prefix match catches them all. The sessionId
+     * is LIKE-escaped (`\`, `%`, `_`) so a crafted id can never widen the match across tenants. Returns rows removed.
+     *
+     * 🔴 NO SQL owner guard (adversarial-review MEDIUM, deliberate): tool_result is keyed ONLY by `ref` — there is
+     * no `session_id` (or `owner`) column to guard on, and the ref is not a session_meta foreign key, so an
+     * owner sub-select would be an awkward ref-correlated EXISTS. This purge stays ROUTE-guarded (the DELETE route
+     * owner-matches the session via `ownerOf` before calling, and the owner-guarded run-ledger delete runs first in
+     * the same coordinator) — belt-and-suspenders only, not an exploitable leak. The LIKE-escape below is the
+     * data-layer protection that matters (a crafted id can't widen the prefix across tenants).
+     */
     deleteBySession(sessionId: string): Promise<number>;
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBToolResultStore extends SqlToolResultStore {
     constructor(pool: MySqlPool);
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgToolResultStore extends SqlToolResultStore {
     constructor(pool: PgPool);
 }

package/dist/plugins/tool-result-store-sql.js

@@ -1,6 +1,9 @@
 import { escapeLike } from "./sql-escape.js";
 import { pgSanitizeText } from "./pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
+/** PG schema for the tool_result table — the PG translation of tidb-pool.ts's tool_result DDL
+ *  (LONGTEXT→TEXT, DATETIME(3)→TIMESTAMPTZ(3), inline KEY→separate CREATE INDEX). Disjoint from other stores'
+ *  tables, so a self-contained ensureSchema is safe (central pg-pool aggregation is done separately). */
 export const PG_TOOL_RESULT_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS tool_result (
      ref        VARCHAR(190) NOT NULL,
@@ -10,57 +13,90 @@ export const PG_TOOL_RESULT_SCHEMA = [
    )`,
     `CREATE INDEX IF NOT EXISTS idx_tool_result_created ON tool_result (created_at)`,
 ];
+/** Idempotent schema apply for the tool_result table (for the integration test to call). */
 export async function ensureSchema(pool) {
     for (const stmt of PG_TOOL_RESULT_SCHEMA)
         await pool.query(stmt);
 }
+/** Dual-dialect durable ToolResultStore. See the file header for the dialect-delta ledger. */
 export class SqlToolResultStore {
     db;
     constructor(db) {
         this.db = db;
     }
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
     async put(ref, content) {
+        // Sanitize invalid UTF-16 (lone/half surrogates — a JS string CAN hold them, e.g. a binary-ish tool
+        // output) to U+FFFD so the column accepts the FULL value via a Buffer utf8 round-trip (valid content is
+        // unchanged). Shared by both dialects.
         let safe = Buffer.from(content, "utf8").toString("utf8");
+        // 🔴 Genuine algorithm divergence (not just SQL text): TiDB's `INSERT IGNORE` downgrades an invalid-byte
+        // rejection to a warning + SILENT TRUNCATION (the utf8 round-trip above is enough — TiDB never sees a NUL
+        // complaint). PG's `ON CONFLICT DO NOTHING` does NOT paper over an encoding error — it errors — and node-pg's
+        // TEXT columns additionally reject a bare NUL (u0000) that a lone-surrogate round-trip alone does NOT strip
+        // (codex H4). `pgSanitizeText` double-scans (NUL + lone surrogate → U+FFFD) so PG never sees either. Never
+        // "unify" onto one engine's sanitize: TiDB doesn't need the NUL scan, and skipping it on PG reintroduces 22P05.
         if (this.db.dialect === "pg")
             safe = pgSanitizeText(safe);
+        // write-once / keep-first: a replay re-puts the SAME ref+content → IGNORE / DO NOTHING keeps the original row.
         await this.db.query(this.q("INSERT IGNORE INTO tool_result (ref, content, created_at) VALUES (?,?,?)", "INSERT INTO tool_result (ref, content, created_at) VALUES ($1,$2,$3) ON CONFLICT (ref) DO NOTHING"), [ref, safe, new Date()]);
     }
     async get(ref, opts = {}) {
         const offset = Math.max(0, Math.floor(opts.offset ?? 0));
         const hasLimit = opts.limit !== undefined && Number.isFinite(opts.limit);
         const limit = hasLimit ? Math.max(0, Math.floor(opts.limit)) : 0;
+        // One round-trip: SUBSTRING is 1-indexed (offset+1); CHAR_LENGTH gives the full (character) length for the
+        // slice header. With no limit, return the remainder from `offset`.
         const sql = hasLimit
             ? this.q("SELECT SUBSTRING(content, ?, ?) AS slice, CHAR_LENGTH(content) AS total FROM tool_result WHERE ref = ?", "SELECT SUBSTRING(content FROM $1::int FOR $2::int) AS slice, CHAR_LENGTH(content) AS total FROM tool_result WHERE ref = $3")
             : this.q("SELECT SUBSTRING(content, ?) AS slice, CHAR_LENGTH(content) AS total FROM tool_result WHERE ref = ?", "SELECT SUBSTRING(content FROM $1::int) AS slice, CHAR_LENGTH(content) AS total FROM tool_result WHERE ref = $2");
         const params = hasLimit ? [offset + 1, limit, ref] : [offset + 1, ref];
         const { rows } = await this.db.query(sql, params);
         if (rows.length === 0)
-            return undefined;
+            return undefined; // unknown ref (e.g. reaped) → core reports "no longer available"
         return { content: String(rows[0].slice ?? ""), offset, totalChars: Number(rows[0].total) };
     }
+    /** TTL reap: delete results older than `cutoffMs`. Returns rows removed. */
     async reapOlderThan(cutoffMs) {
         try {
             const { affected } = await this.db.query(this.q("DELETE FROM tool_result WHERE created_at < ?", "DELETE FROM tool_result WHERE created_at < $1"), [new Date(cutoffMs)]);
             return affected;
         }
         catch {
-            return 0;
+            return 0; // best-effort reaper — never throw into the loop
         }
     }
+    /**
+     * E21 (§0.5 session delete) — purge offloaded tool results for one session. core namespaces every ref as
+     * `tr_<sessionId>_<toolCallId>`, so a `LIKE 'tr_<sessionId>_%'` prefix match catches them all. The sessionId
+     * is LIKE-escaped (`\`, `%`, `_`) so a crafted id can never widen the match across tenants. Returns rows removed.
+     *
+     * 🔴 NO SQL owner guard (adversarial-review MEDIUM, deliberate): tool_result is keyed ONLY by `ref` — there is
+     * no `session_id` (or `owner`) column to guard on, and the ref is not a session_meta foreign key, so an
+     * owner sub-select would be an awkward ref-correlated EXISTS. This purge stays ROUTE-guarded (the DELETE route
+     * owner-matches the session via `ownerOf` before calling, and the owner-guarded run-ledger delete runs first in
+     * the same coordinator) — belt-and-suspenders only, not an exploitable leak. The LIKE-escape below is the
+     * data-layer protection that matters (a crafted id can't widen the prefix across tenants).
+     */
     async deleteBySession(sessionId) {
+        // Escape the WHOLE literal prefix `tr_<sessionId>_` (incl. both literal underscores) so the only LIKE wildcard
+        // is the trailing `%` — a `_` left un-escaped is a single-char wildcard that could over-match across tenants.
         const prefix = `${escapeLike(`tr_${sessionId}_`)}%`;
+        // Explicit `ESCAPE` clause — see the file-header dialect-delta note for why each dialect spells it as it does.
         const { affected } = await this.db.query(this.q("DELETE FROM tool_result WHERE ref LIKE ? ESCAPE '\\\\'", "DELETE FROM tool_result WHERE ref LIKE $1 ESCAPE '\\'"), [prefix]);
         return affected;
     }
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export class TiDBToolResultStore extends SqlToolResultStore {
     constructor(pool) {
         super(mysqlDriver(pool));
     }
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export class PgToolResultStore extends SqlToolResultStore {
     constructor(pool) {
         super(pgDriver(pool));

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

@@ -1,10 +1,31 @@
+/**
+ * design/102 (K-8 CC full-body) — the WebSearch BACKEND (BRAIN / model-service leg) that core leaves
+ * deployment-injected (`WebSearchConfig.search`; core ships NONE, the same boundary as the model gateway). Wiring a
+ * 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)
+ *   - `tavily`  — Tavily Search API (POST, `Authorization: Bearer`, native include/exclude_domains)
+ *   - `searxng` — a self-hosted SearXNG instance (GET `?format=json`, no auth)
+ *
+ * Each returns `{ title, url, snippet }[]`; core does the rest — it `delimitUntrusted`-fences the (UNTRUSTED) results
+ * and re-enforces the `allowed_domains`/`blocked_domains` FLOOR on them, so honoring `opts` here is an optimization,
+ * not a correctness requirement (a backend MAY ignore it). The API key comes from deployment env — it never enters
+ * the model prompt or the tool args. `effect:"read"` (idempotent) is core's concern; this is just the transport.
+ */
+/** Search providers this backend speaks. Absent `WEB_SEARCH_PROVIDER` ⇒ no backend ⇒ WebSearch is not assembled. */
 export type WebSearchProvider = "brave" | "tavily" | "searxng";
 export interface WebSearchBackendConfig {
     readonly provider: WebSearchProvider;
+    /** API key (brave/tavily). From `WEB_SEARCH_API_KEY` — never reaches the model. */
     readonly apiKey?: string;
+    /** SearXNG instance base URL (REQUIRED for searxng); for brave/tavily an optional base-URL override (proxy/test). */
     readonly endpoint?: string;
+    /** Max results returned to the model (clamped 1..20; default 10). */
     readonly maxResults?: number;
+    /** Per-search wall-clock (ms, default 10000). */
     readonly timeoutMs?: number;
+    /** Injectable for tests. */
     readonly fetchImpl?: typeof fetch;
 }
 export interface WebSearchResult {
@@ -16,13 +37,27 @@ export interface WebSearchOpts {
     allowedDomains?: string[];
     blockedDomains?: string[];
 }
+/** The shape core's `WebSearchConfig.search` expects (back-compatible 2- or 3-arg). */
 export type WebSearchFn = (query: string, signal?: AbortSignal, opts?: WebSearchOpts) => Promise<WebSearchResult[]>;
+/** The live object `createWebSearchBackend` produces — a `search` fn (provider + API key captured in the closure) + the effective result cap. */
 export interface WebSearchBackend {
     search: WebSearchFn;
     maxResults: number;
 }
 export declare function setWebSearchBadPayloadObserver(fn: ((provider: string) => void) | undefined): void;
+/**
+ * Build the `WebSearchConfig` (a `search` fn + `maxResults`) for `assembleFullBodyTools({ webSearch })`. The API key
+ * stays captured in this closure — it is never surfaced to the model or the tool args.
+ */
 export declare function createWebSearchBackend(cfg: WebSearchBackendConfig): WebSearchBackend;
+/** Parse the deployment env into a backend config; `undefined` when no provider is set (⇒ WebSearch not assembled). */
 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 — design/107 axis).
+ */
 export declare function webSearchConfigFromSettings(raw: unknown): WebSearchBackendConfig | undefined;
 //# sourceMappingURL=web-search.d.ts.map

package/dist/plugins/web-search.js

@@ -1,7 +1,23 @@
+/**
+ * design/102 (K-8 CC full-body) — the WebSearch BACKEND (BRAIN / model-service leg) that core leaves
+ * deployment-injected (`WebSearchConfig.search`; core ships NONE, the same boundary as the model gateway). Wiring a
+ * 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)
+ *   - `tavily`  — Tavily Search API (POST, `Authorization: Bearer`, native include/exclude_domains)
+ *   - `searxng` — a self-hosted SearXNG instance (GET `?format=json`, no auth)
+ *
+ * Each returns `{ title, url, snippet }[]`; core does the rest — it `delimitUntrusted`-fences the (UNTRUSTED) results
+ * and re-enforces the `allowed_domains`/`blocked_domains` FLOOR on them, so honoring `opts` here is an optimization,
+ * not a correctness requirement (a backend MAY ignore it). The API key comes from deployment env — it never enters
+ * the model prompt or the tool args. `effect:"read"` (idempotent) is core's concern; this is just the transport.
+ */
 const DEFAULT_MAX_RESULTS = 10;
 const DEFAULT_TIMEOUT_MS = 10_000;
 const BRAVE_BASE = "https://api.search.brave.com/res/v1/web/search";
 const TAVILY_BASE = "https://api.tavily.com/search";
+/** Combine the caller's AbortSignal with a per-search timeout into one signal; `done()` clears the timer + listener. */
 function withTimeout(signal, ms) {
     const ctrl = new AbortController();
     const onAbort = () => ctrl.abort();
@@ -18,6 +34,13 @@ function withTimeout(signal, ms) {
 async function errorText(res) {
     return (await res.text().catch(() => "")).slice(0, 200);
 }
+/**
+ * Normalize an UNTRUSTED provider results payload: guard a non-array (a misconfigured proxy / buggy self-hosted
+ * SearXNG could return a non-list or null elements), skip null/non-object rows, coerce every field to a string, drop
+ * url-less rows, cap to max. `pick` maps each provider's row to the common shape (Brave→description, others→content).
+ */
+/** LOW (SILENT-FALLBACK P1): a provider returning a non-array `results` used to silently become zero results
+ *  for the model. main.ts wires this to web_search_bad_payload_total{provider} + a warn. */
 let onBadPayload;
 export function setWebSearchBadPayloadObserver(fn) {
     onBadPayload = fn;
@@ -28,18 +51,18 @@ function normalize(raw, pick, max, provider) {
             try {
                 onBadPayload?.(provider);
             }
-            catch { }
+            catch { /* observability never breaks search */ }
         }
-        return [];
-    }
+        return []; // absent field (undefined/null) = legitimately empty; a PRESENT non-array = malformed payload
+    } // 🔴 review LOW: a non-array `results` must not throw a raw TypeError upstream
     const out = [];
     for (const row of raw) {
         if (!row || typeof row !== "object")
-            continue;
+            continue; // a null / non-object element is not a result
         const f = pick(row);
         const url = typeof f.url === "string" ? f.url : "";
         if (!url)
-            continue;
+            continue; // no URL ⇒ useless to the model (and to core's domain re-enforcement)
         out.push({ title: typeof f.title === "string" ? f.title : "", url, snippet: typeof f.snippet === "string" ? f.snippet : "" });
         if (out.length >= max)
             break;
@@ -51,7 +74,8 @@ async function braveSearch(fetchImpl, cfg, query, max, signal) {
         throw new Error("WEB_SEARCH_API_KEY is required for the brave provider");
     const url = new URL(cfg.endpoint || BRAVE_BASE);
     url.searchParams.set("q", query);
-    url.searchParams.set("count", String(Math.min(20, max)));
+    url.searchParams.set("count", String(Math.min(20, max))); // Brave caps count at 20
+    // Brave has no native include/exclude_domains param — core re-enforces the domain floor on the results.
     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)}`);
@@ -63,7 +87,7 @@ async function tavilySearch(fetchImpl, cfg, query, max, signal, opts) {
         throw new Error("WEB_SEARCH_API_KEY is required for the tavily provider");
     const body = { query, max_results: Math.min(20, max) };
     if (opts?.allowedDomains?.length)
-        body.include_domains = opts.allowedDomains.slice(0, 300);
+        body.include_domains = opts.allowedDomains.slice(0, 300); // Tavily native domain filter
     if (opts?.blockedDomains?.length)
         body.exclude_domains = opts.blockedDomains.slice(0, 150);
     const res = await fetchImpl(cfg.endpoint || TAVILY_BASE, {
@@ -80,15 +104,19 @@ async function tavilySearch(fetchImpl, cfg, query, max, signal, opts) {
 async function searxngSearch(fetchImpl, cfg, query, max, signal) {
     if (!cfg.endpoint)
         throw new Error("WEB_SEARCH_ENDPOINT (the SearXNG instance URL) is required for the searxng provider");
-    const url = new URL("/search", cfg.endpoint);
+    const url = new URL("/search", cfg.endpoint); // endpoint is the deployment-configured instance base (trusted, not model-controlled)
     url.searchParams.set("q", query);
     url.searchParams.set("format", "json");
-    const res = await fetchImpl(url, { headers: { Accept: "application/json" }, signal });
+    const res = await fetchImpl(url, { headers: { Accept: "application/json" }, signal }); // SearXNG needs no auth
     if (!res.ok)
         throw new Error(`searxng search failed (${res.status}): ${await errorText(res)}`);
     const data = (await res.json());
     return normalize(data.results, (r) => ({ title: r.title, url: r.url, snippet: r.content }), max, "searxng");
 }
+/**
+ * Build the `WebSearchConfig` (a `search` fn + `maxResults`) for `assembleFullBodyTools({ webSearch })`. The API key
+ * stays captured in this closure — it is never surfaced to the model or the tool args.
+ */
 export function createWebSearchBackend(cfg) {
     const fetchImpl = cfg.fetchImpl ?? fetch;
     const maxResults = Math.max(1, Math.min(20, cfg.maxResults ?? DEFAULT_MAX_RESULTS));
@@ -111,6 +139,7 @@ export function createWebSearchBackend(cfg) {
     };
     return { search, maxResults };
 }
+/** Parse the deployment env into a backend config; `undefined` when no provider is set (⇒ WebSearch not assembled). */
 export function webSearchConfigFromEnv(env = process.env) {
     const provider = env.WEB_SEARCH_PROVIDER?.trim().toLowerCase();
     if (provider !== "brave" && provider !== "tavily" && provider !== "searxng")
@@ -125,6 +154,13 @@ export function webSearchConfigFromEnv(env = process.env) {
         ...(Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? { timeoutMs: Math.floor(timeoutRaw) } : {}),
     };
 }
+/**
+ * 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 — design/107 axis).
+ */
 export function webSearchConfigFromSettings(raw) {
     if (!raw || typeof raw !== "object")
         return undefined;

package/dist/plugins/workflow-journal-limits.d.ts

@@ -1,2 +1,12 @@
+/**
+ * SVC-2 — the shared size bound for a journaled workflow-agent result, so all THREE backends (tidb/pg SQL
+ * twins here + core's FileWorkflowJournalStore) DEGRADE IDENTICALLY on an oversize TaskResult: skip-journal
+ * (a no-op, never insert/throw) — the agent's ordinal is simply not cached and a resume re-runs that one
+ * agent live. Rationale (TiDB ~6 MiB txn-entry-size-limit vs PG/file no such limit) documented at the source.
+ *
+ * Now a RE-EXPORT of core's copy: the constant + helper moved to core with the FileWorkflowJournalStore
+ * adoption (core 1.223.0 — core inlined them into its store file and exports both).
+ * The SQL twins import from here unchanged; one source of truth for the byte-match contract.
+ */
 export { MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "@sema-agent/core";
 //# sourceMappingURL=workflow-journal-limits.d.ts.map

package/dist/plugins/workflow-journal-limits.js

@@ -1,2 +1,12 @@
+/**
+ * SVC-2 — the shared size bound for a journaled workflow-agent result, so all THREE backends (tidb/pg SQL
+ * twins here + core's FileWorkflowJournalStore) DEGRADE IDENTICALLY on an oversize TaskResult: skip-journal
+ * (a no-op, never insert/throw) — the agent's ordinal is simply not cached and a resume re-runs that one
+ * agent live. Rationale (TiDB ~6 MiB txn-entry-size-limit vs PG/file no such limit) documented at the source.
+ *
+ * Now a RE-EXPORT of core's copy: the constant + helper moved to core with the FileWorkflowJournalStore
+ * adoption (core 1.223.0 — core inlined them into its store file and exports both).
+ * The SQL twins import from here unchanged; one source of truth for the byte-match contract.
+ */
 export { MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "@sema-agent/core";
 //# sourceMappingURL=workflow-journal-limits.js.map

package/dist/plugins/workflow-journal-store-sql.d.ts

@@ -1,7 +1,50 @@
+/**
+ * Durable {@link WorkflowJournalStore} (SVC-2, core CORE-7) — SINGLE-FILE DUAL-DIALECT (design/158 A12
+ * 定型半场). ONE implementation, TWO dialects; the historical `TiDBWorkflowJournalStore` / `PgWorkflowJournalStore`
+ * class names survive as thin ctor subclasses so every consumer (store-backend.ts, the extreme/integration/
+ * resume-fork-probe suites) is untouched.
+ *
+ * This is the cross-replica resume journal for an LLM-authored workflow. core ships
+ * {@link import("@sema-agent/core").InMemoryWorkflowJournalStore} (single-replica, lost on crash); this is the
+ * byte-match durable twin so a workflow survives a replica crash and RESUMES (replay the longest unchanged
+ * PREFIX of recorded `ctx.agent` results, run only the first changed/new call + everything after it live). The
+ * journal is LOAD-BEARING (unlike the best-effort {@link import("./tidb-run-store.js")} observation layer):
+ * append/load failures MUST throw — a silently-dropped entry would silently re-run already-done work.
+ *
+ * Schema = `workflow_journal (run_id, ordinal) PK` (DDL in tidb-pool.ts / pg-pool.ts ensureSchema). `ordinal`
+ * is the positional index a callKey was minted at, derived with core's {@link callKeyOrdinal} (NEVER
+ * hand-parsed — a malformed key falls back to ordinal 0 there, matching the InMemory store). `result` holds
+ * `JSON.stringify(entry.result)` (a TaskResult is plain serializable data). The PK makes append IDEMPOTENT per
+ * (run_id, ordinal): a second append for the same ordinal OVERWRITES (last-write-wins) — a resumed run
+ * re-appends its replayed prefix verbatim, so this is the exact InMemory `byOrdinal.set(ordinal, …)` semantics,
+ * not a duplicate row.
+ *
+ * ── Dialect deltas, kept EXPLICIT ────────────────────────────────────────────────────────────────────
+ *   - `?` placeholders vs `$n`
+ *   - `ON DUPLICATE KEY UPDATE … VALUES(col)` vs `ON CONFLICT (run_id, ordinal) DO UPDATE SET … EXCLUDED.col`
+ *   - `LENGTH(result)` (TiDB — byte length) vs `OCTET_LENGTH(result)` (PG — `LENGTH(text)` is CHARACTER count;
+ *     a multi-byte UTF-8 payload would silently slip past the byte-budget cap on PG with plain `LENGTH`, so
+ *     the twin uses the byte-counting function instead — codex R3, real dual-DB-suite-confirmed) in `loadPage`'s
+ *     size-gate CASE.
+ *   - `loadPage`'s bind-param ORDER: TiDB's `?`s appear in query-text order (maxResultBytes first, inside the
+ *     CASE, ahead of runId/scope), so its params array is `[maxResultBytes, runId, scope, limit, offset]`; PG's
+ *     `$n` are POSITIONAL (not text-order), so its array is `[runId, scope, maxResultBytes, limit, offset]`
+ *     (`$3` inside the CASE refers to the third element regardless of where `$3` sits in the text). Same
+ *     placeholder-arity-fallout class the sql-driver.ts header calls out for null-safe compares.
+ *   - affectedRows vs rowCount (via SqlDriver's normalized `affected`).
+ *   - schema ownership: TiDB DDL in tidb-pool.ts, PG DDL in pg-pool.ts (neither store creates tables).
+ */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type WorkflowJournalEntry, type WorkflowJournalStore } from "@sema-agent/core";
 import { type SqlDriver } from "./sql-driver.js";
+/** Dual-dialect durable WorkflowJournalStore. See the file header for the dialect-delta ledger. */
+/** RB-242 租约旋钮。TTL 只是**崩溃兜底**(engine 终态 finally 显式释放;[1981]/[1984] 两层分工:
+ *  engine 崩了没释放 ⇒ 陈旧 claim 可被接管)。
+ *  🔴 缺省 1h,与 core file 参考实现同值([1984] :284)——**租约无心跳**(claimed_at 在授予时刻定格,
+ *  运行期间不刷新),所以 TTL 必须盖过最长合法 run 时长:取小了(我初版 15min)会在一次 >TTL 的活跑
+ *  中把 claim 判陈旧、放另一副本进来接管——恰是本缝要防的双跑。要更短的接管等待,先给 engine 半场
+ *  加心跳刷新,再谈调小。 */
 export interface SqlWorkflowJournalStoreOptions {
     resumeClaimTtlMs?: number;
 }
@@ -9,10 +52,26 @@ export declare class SqlWorkflowJournalStore implements WorkflowJournalStore {
     private readonly db;
     private readonly resumeClaimTtlMs;
     constructor(db: SqlDriver, opts?: SqlWorkflowJournalStoreOptions);
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
+    /** Record one agent's result. Idempotent per (run_id, ordinal): the PK upsert OVERWRITES (last-write-wins), so a
+     *  resumed run re-appending its replayed prefix verbatim leaves no duplicate. callKeyOrdinal is the SOLE ordinal
+     *  source (core's parser — a malformed key collapses to 0, matching InMemory). Throws on a REAL failure
+     *  (LOAD-BEARING), EXCEPT an oversize result is skip-journaled (see below) rather than throwing the workflow dead. */
     append(runId: string, scope: string, entry: WorkflowJournalEntry): Promise<void>;
+    /** Entries for `runId` IF its recorded scope === `scope`, ASCENDING by ordinal; otherwise EMPTY. CORE-9 audit
+     *  BLOCKER: scope in the WHERE (twin of WorkflowRunStore) — the LLM controls `resumeFromRunId`, so a cross-scope
+     *  runId resolves to an empty journal (resume safely diverges to live, never discloses another tenant's results).
+     *  Each row's `result` is the persisted JSON.stringify(TaskResult) → JSON.parse back. Throws on failure (LOAD-BEARING). */
     load(runId: string, scope: string): Promise<WorkflowJournalEntry[]>;
+    /** [1412] locator 云形(core 1.353 WorkflowJournalStore.locator additive):SQL 店的 journal 坐标=
+     *  [1402] HTTP 读面路由(file 店返 jsonl 路径=CC 本地形;此处返云形,core 铸 diagnostics 教句时单源引用)。 */
     locator(runId: string, _scope: string): string;
+    /** codex R1-H2:分页投影读——LIMIT/OFFSET 界行数,字节门界单行字节(超限行不取 result 全文,只回字节数;
+     *  读面标 truncated)。ORDER BY ordinal 与 load 同轴。
+     *  🔴 param ORDER differs by dialect (see file header): TiDB's `?`s bind in text order (maxResultBytes first,
+     *  inside the CASE); PG's `$n` are positional, so its array keeps runId/scope first. Never unify — a swap
+     *  silently mis-binds the OTHER dialect's placeholders. */
     loadPage(runId: string, scope: string, opts: {
         offset: number;
         limit: number;
@@ -22,7 +81,18 @@ export declare class SqlWorkflowJournalStore implements WorkflowJournalStore {
         resultJson: string | null;
         resultBytes: number;
     }>>;
+    /** GC — purge ALL journal entries for a run (the run reaper calls this once the run is terminal + retained). Scoped
+     *  by run_id alone; idempotent (affected-row count). Mirrors the resume-anchor store's deleteBySession. */
     deleteByRun(runId: string): Promise<number>;
+    /** RB-242 / WF2([1981] core 拍板 a 形,签名逐字)—— cross-replica resume admission lease。
+     *
+     *  语义(bake-store `idem_key UNIQUE` 先例):PK (source_run_id, scope) 上的原子赢或观察。四步,每步
+     *  单语句原子,并发交叉在任一步都收敛到「恰一个持有者」:
+     *   ① 抢空位:INSERT..DO NOTHING / ON DUP KEY 无操作 —— affected=1 即赢;
+     *   ② 同持有者幂等重入(engine 重试同一 resume):按 (键, new_run_id) 守卫的 claimed_at 刷新;
+     *   ③ TTL 崩溃兜底接管:claimed_at < now-ttl 守卫下的原子改持有者(engine 终态会显式释放,
+     *     走到这步=上一持有 engine 崩了没释放;两层分工见 SqlWorkflowJournalStoreOptions 注);
+     *   ④ 都没赢 ⇒ 读在位者返 {granted:false, holder}(holder 进 engine 的拒绝文案供归因)。 */
     resumeClaim(input: {
         sourceRunId: string;
         newRunId: string;
@@ -31,16 +101,24 @@ export declare class SqlWorkflowJournalStore implements WorkflowJournalStore {
         granted: boolean;
         holder?: string;
     }>;
+    /** 只有 holder 能释放(new_run_id 守卫)—— engine 在 newRunId 终态/放弃时调;非 holder 调用=no-op。 */
     releaseResumeClaim(input: {
         sourceRunId: string;
         newRunId: string;
         scope: string;
     }): Promise<void>;
+    /** GC — time-based sweep: purge journal entries older than `maxAgeMs` (created_at < now - maxAgeMs). The
+     *  per-run deleteByRun has no production caller (a run-store reap gives no per-run hook), so this bounded sweep
+     *  — wired into the service reaper — is what keeps the heaviest table (TaskResult-bearing) from growing without
+     *  bound. A resume of a journal older than the retention window simply re-runs live (resume is an optimization).
+     *  Idempotent; returns the rows purged. */
     reapExpired(now: number, maxAgeMs: number): Promise<number>;
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBWorkflowJournalStore extends SqlWorkflowJournalStore {
     constructor(pool: MySqlPool, opts?: SqlWorkflowJournalStoreOptions);
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgWorkflowJournalStore extends SqlWorkflowJournalStore {
     constructor(pool: PgPool, opts?: SqlWorkflowJournalStoreOptions);
 }