@thincoder/core 0.9.1

package/conventions.mjs

@@ -0,0 +1,223 @@
+/**
+ * conventions.mjs — the single authority for code / doc / temp path classification,
+ * plus the project convention declaration surface (`.thincoder/conventions.json`).
+ *
+ * Why one module: engineering-mode gates and guards (design gate, review-doc gate,
+ * mutation accounting, verify fast path) each carried their own copy of the
+ * "what counts as product code" predicate — anchored `^src/` regexes, `docs/`
+ * prefix checks, component regexes. Each copy drifted, and each hardcoded THIS
+ * repository's layout: a project whose code lives outside `src/` slipped through
+ * the design gate silently (PORTABILITY FR12 / PO-10). One classifier + one
+ * declaration file = one truth.
+ *
+ * Defaults are DATA (`DEFAULT_CODE_PATHS`) — overridable per project through the
+ * declaration file (§4.1 schema). Missing file → pure defaults (no noise);
+ * corrupt/unreadable file → defaults + console.warn + a log event (never crash,
+ * never swallow — PORTABILITY FR10).
+ *
+ * Classification vocabulary (PORTABILITY design §3.1):
+ *   code — inside a declared code segment (default: the path segment `src`), or
+ *          not a documentation extension;  doc — documentation extension outside
+ *          any code segment;  temp — tmp-* name or .tmp/.temp extension.
+ */
+import { readFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { logEvent } from "./log.mjs"
+
+/** Default code-path segments (data, not logic — a project may replace them). */
+export const DEFAULT_CODE_PATHS = ["src"]
+
+/** Project declaration file, relative to the project root. */
+export const CONVENTIONS_REL_PATH = ".thincoder/conventions.json"
+
+/** Documentation predicate (moved here verbatim from advisor/repos.mjs — one copy). */
+const DOC_FILE = /(?:^|[/\\])(?:LICENSE|NOTICE|CHANGELOG|AUTHORS)(?:\.\w+)?$|\.(?:md|markdown|mdx|txt|rst|adoc)$/i
+
+/** Temp/scratch predicate (moved here verbatim from advisor/repos.mjs). */
+const TEMP_FILE = /(?:^|[/\\])tmp-[^/\\]+$|\.(?:tmp|temp)$/i
+
+/** True when a path is a throwaway temp file (tmp-* name or .tmp/.temp extension). */
+export function isTempPath(p) {
+  return TEMP_FILE.test(p ?? "")
+}
+
+/** Path → segments (both separators accepted; absolute and relative alike). */
+function segmentsOf(p) {
+  return String(p ?? "").replace(/\\/g, "/").split("/").filter(Boolean)
+}
+
+/**
+ * True when the path contains a declared code segment sequence at any depth.
+ * Segment matching (not a prefix anchor) is what closes the nested-layout hole:
+ * `packages/foo/src/x.md` is product code, not a document. Comparison is
+ * case-insensitive — on case-insensitive filesystems `Src/x.mjs` is the same
+ * directory, and the gate must not be bypassable by casing.
+ */
+function hasCodeSegment(p, conv) {
+  const parts = segmentsOf(p).map((s) => s.toLowerCase())
+  const wanted = conv?.codePaths ?? DEFAULT_CODE_PATHS
+  for (const entry of wanted) {
+    const want = segmentsOf(entry).map((s) => s.toLowerCase())
+    if (want.length === 0) continue
+    for (let i = 0; i + want.length <= parts.length; i++) {
+      if (want.every((seg, j) => parts[i + j] === seg)) return true
+    }
+  }
+  return false
+}
+
+/** "code" | "doc" | "temp" — the single classification decision.
+ *  Precedence: code segment first (src/** stays product code even when the name
+ *  looks scratch — the pre-existing unconditional-src rule), then temp, then a
+ *  documentation extension, else code (anything not doc/temp is product code). */
+export function classifyPath(p, conv) {
+  const s = String(p ?? "")
+  if (hasCodeSegment(s, conv)) return "code"
+  if (TEMP_FILE.test(s)) return "temp"
+  if (DOC_FILE.test(s)) return "doc"
+  return "code"
+}
+
+/** True when the path is product code (see classifyPath for the precedence). */
+export function isCodePath(p, conv) {
+  return classifyPath(p, conv) === "code"
+}
+
+/** True when the path is a documentation file — a doc extension that does NOT
+ *  live inside a declared code segment (src/prompts/*.md is product code). */
+export function isDocPath(p, conv) {
+  const s = String(p ?? "")
+  return DOC_FILE.test(s) && !hasCodeSegment(s, conv)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Declaration loading (cached per project root — `clearConventionsCache()` is
+// the test seam; declaration files change rarely and only at session scope).
+// ─────────────────────────────────────────────────────────────────────────────
+
+function normalizeExtensions(v) {
+  if (!Array.isArray(v)) return []
+  const out = []
+  for (const e of v) {
+    if (typeof e !== "string") continue
+    const t = e.trim().toLowerCase()
+    if (!t) continue
+    const ext = t.startsWith(".") ? t : `.${t}`
+    if (!out.includes(ext)) out.push(ext)
+  }
+  return out
+}
+
+/** Declared code paths replace the default (replacement, not union — §4.1). */
+function normalizeCodePaths(v) {
+  if (!Array.isArray(v)) return null
+  const out = []
+  for (const e of v) {
+    if (typeof e !== "string") continue
+    const s = e.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "")
+    if (!s || out.includes(s)) continue
+    out.push(s)
+  }
+  return out.length > 0 ? out : null
+}
+
+function normalizeString(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : ""
+}
+
+/** Per-key type check for recognized keys (present but wrong type). §3.2/§4.1: a
+ *  type error degrades WITH a warning — never silently (the fallback semantics stay
+ *  per-key; only the visibility is added here). */
+function typeErrorsOf(raw) {
+  const isObj = (v) => v !== undefined && v !== null && typeof v === "object" && !Array.isArray(v)
+  const strArray = (v) => Array.isArray(v) && v.every((x) => typeof x === "string")
+  const errs = []
+  if (raw.codePaths !== undefined && !strArray(raw.codePaths)) errs.push("codePaths must be an array of strings")
+  const idx = raw.index
+  if (idx !== undefined && !isObj(idx)) errs.push("index must be an object")
+  else if (isObj(idx)) {
+    for (const k of ["codeExtensions", "docExtensions"]) {
+      if (idx[k] !== undefined && !strArray(idx[k])) errs.push(`index.${k} must be an array of strings`)
+    }
+  }
+  const adv = raw.advisor
+  if (adv !== undefined && !isObj(adv)) errs.push("advisor must be an object")
+  else if (isObj(adv)) {
+    for (const k of ["docMap", "standardsDoc"]) {
+      if (adv[k] !== undefined && typeof adv[k] !== "string") errs.push(`advisor.${k} must be a string`)
+    }
+  }
+  return errs
+}
+
+function buildConventions(raw) {
+  const codePaths = normalizeCodePaths(raw?.codePaths)
+  const codeExtensions = normalizeExtensions(raw?.index?.codeExtensions)
+  const docExtensions = normalizeExtensions(raw?.index?.docExtensions)
+  const docMap = normalizeString(raw?.advisor?.docMap)
+  const standardsDoc = normalizeString(raw?.advisor?.standardsDoc)
+  // `declared` = the declaration actually took effect (at least one recognized key
+  // honored) — the design-gate hint reads it to decide whether to point at the
+  // declaration file ("declare project conventions … to adjust").
+  const declared = Boolean(codePaths || codeExtensions.length || docExtensions.length || docMap || standardsDoc)
+  return Object.freeze({
+    declared,
+    codePaths: Object.freeze(codePaths ?? [...DEFAULT_CODE_PATHS]),
+    index: Object.freeze({
+      codeExtensions: Object.freeze(codeExtensions),
+      docExtensions: Object.freeze(docExtensions),
+    }),
+    advisor: Object.freeze({ docMap, standardsDoc }),
+  })
+}
+
+/** Full-default conventions (no declaration) — the fallback every consumer gets. */
+export const DEFAULT_CONVENTIONS = buildConventions(null)
+
+const _cache = new Map()
+
+/** Drop the per-root cache (test seam — declaration files are read once per root). */
+export function clearConventionsCache() {
+  _cache.clear()
+}
+
+/**
+ * Load (and cache) the normalized conventions for a project root.
+ * @param {string} cwd — project root (declaration lives at .thincoder/conventions.json)
+ * @returns {Readonly<{declared: boolean, codePaths: readonly string[],
+ *   index: {codeExtensions: string[], docExtensions: string[]},
+ *   advisor: {docMap: string, standardsDoc: string}}>}
+ */
+export function loadConventions(cwd) {
+  const root = resolve(cwd ?? process.cwd())
+  const hit = _cache.get(root)
+  if (hit) return hit
+  let conv = DEFAULT_CONVENTIONS
+  try {
+    const text = readFileSync(join(root, CONVENTIONS_REL_PATH), "utf8")
+    try {
+      const raw = JSON.parse(text)
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("top level must be a JSON object")
+      conv = buildConventions(raw)
+      const typeErrs = typeErrorsOf(raw)
+      if (typeErrs.length > 0) {
+        // Wrong-typed keys fall back per-key — but the user must SEE that their
+        // declaration did not take effect (never silently swallowed).
+        console.warn(`[conventions] ${CONVENTIONS_REL_PATH} has invalid value types (${typeErrs.join("; ")}) — those keys fall back to defaults`)
+        logEvent("conventions:error", { cwd: root, err: `type errors: ${typeErrs.join("; ").slice(0, 160)}` })
+      }
+    } catch (e) {
+      // Corrupt file / wrong shape → defaults, visible: warn + event (never silent).
+      console.warn(`[conventions] ${CONVENTIONS_REL_PATH} unreadable (${e?.message ?? e}) — falling back to defaults`)
+      logEvent("conventions:error", { cwd: root, err: String(e?.message ?? e).slice(0, 200) })
+    }
+  } catch (e) {
+    if (e?.code !== "ENOENT") {
+      // File exists but cannot be read (EACCES etc.) — same visible degradation.
+      console.warn(`[conventions] ${CONVENTIONS_REL_PATH} not readable (${e?.message ?? e}) — falling back to defaults`)
+      logEvent("conventions:error", { cwd: root, err: String(e?.message ?? e).slice(0, 200) })
+    }
+  }
+  _cache.set(root, conv)
+  return conv
+}

package/embedding.mjs

@@ -0,0 +1,120 @@
+/**
+ * embedding.mjs — vector embeddings
+ * OpenAI-compatible /v1/embeddings (SiliconFlow bge-m3 / Ollama / OpenAI all supported),
+ * reuses provider.mjs fetch + retry pattern, zero dependencies.
+ * Vectors are normalized before storage; dot product then equals cosine similarity.
+ */
+
+import { RETRYABLE_STATUS } from "./provider/index.mjs"
+const MAX_RETRIES = 3
+const BATCH_SIZE = 32 // max texts per request (within SiliconFlow limits)
+
+/** Create an embedder. config: { baseURL, apiKey, model } */
+export function createEmbedder(config) {
+  if (!config?.baseURL) throw new Error("embedding config: baseURL is required — configure embedding.baseURL in ~/.thincoder/config.json")
+  if (!config?.apiKey) throw new Error("embedding config: apiKey is required — configure embedding.apiKey in ~/.thincoder/config.json")
+  if (!config?.model) throw new Error("embedding config: model is required — configure embedding.model in ~/.thincoder/config.json")
+  return {
+    baseURL: config.baseURL.replace(/\/+$/, ""),
+    apiKey: config.apiKey,
+    model: config.model,
+  }
+}
+
+/**
+ * Batch embedding. texts: string[] → Float32Array[] (normalized)
+ * Auto-batches, retries on failure (exponential backoff).
+ */
+export async function embed(embedder, texts, { signal } = {}) {
+  if (texts.length === 0) return []
+  const vectors = []
+  for (let i = 0; i < texts.length; i += BATCH_SIZE) {
+    const batch = texts.slice(i, i + BATCH_SIZE)
+    const data = await requestWithRetry(embedder, batch, signal)
+    // Mismatched count is a hard error — silently accepting would misalign vectors with texts, poisoning the entire index
+    if (!Array.isArray(data.data) || data.data.length !== batch.length) {
+      throw new Error(`Embedding API returned ${data.data?.length ?? 0} vectors for ${batch.length} inputs`)
+    }
+    // Spec says data[] order matches input, but sort by index field if present — don't bet on server implementation
+    const items = data.data.every((d) => typeof d.index === "number")
+      ? [...data.data].sort((a, b) => a.index - b.index)
+      : data.data
+    for (const item of items) {
+      vectors.push(normalize(Float32Array.from(item.embedding)))
+    }
+  }
+  return vectors
+}
+
+/** Cosine similarity (inputs are normalized, dot product equals cosine) */
+export function cosine(a, b) {
+  if (a.length !== b.length) return 0
+  let sum = 0
+  const n = a.length
+  for (let i = 0; i < n; i++) sum += a[i] * b[i]
+  return sum
+}
+
+/** Float32Array → Buffer suitable for sqlite BLOB storage */
+export function toBlob(vec) {
+  return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength)
+}
+
+/** sqlite BLOB → Float32Array */
+export function fromBlob(buf) {
+  // BLOB may come from Buffer pool where byteOffset isn't 4-aligned; creating a view directly would RangeError — copy to align first
+  if (buf.byteOffset % 4 !== 0) buf = new Uint8Array(buf)
+  if (buf.byteLength % 4 !== 0) return new Float32Array(0)
+  return new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4)
+}
+
+// ---------------------------------------------------------------- internal
+
+async function requestWithRetry(embedder, input, signal) {
+  let lastError
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    if (attempt > 0) await sleep(2 ** (attempt - 1) * 1000)
+
+    let response
+    try {
+      response = await fetch(`${embedder.baseURL}/embeddings`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${embedder.apiKey}`,
+        },
+        body: JSON.stringify({ model: embedder.model, input }),
+        signal: signal
+          ? AbortSignal.any([signal, AbortSignal.timeout(60_000)])
+          : AbortSignal.timeout(60_000),
+      })
+    } catch (error) {
+      if (error.name === "AbortError") throw error
+      lastError = error
+      continue
+    }
+
+    if (response.ok) return response.json()
+
+    const text = await response.text().catch(() => "")
+    const message = `Embedding API error ${response.status}: ${text}`
+    if (RETRYABLE_STATUS.has(response.status)) {
+      lastError = new Error(message)
+      continue
+    }
+    throw new Error(message)
+  }
+  throw lastError
+}
+
+function normalize(vec) {
+  let sum = 0
+  for (let i = 0; i < vec.length; i++) sum += vec[i] * vec[i]
+  const norm = Math.sqrt(sum) || 1
+  for (let i = 0; i < vec.length; i++) vec[i] /= norm
+  return vec
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/escape.mjs

@@ -0,0 +1,152 @@
+/**
+ * escape.mjs — 中和 OpenAI 兼容服务端在 message content 内做的非标二次转义解析 + 孤立代理净化。
+ *
+ * 两个独立毒源（均真机实证）：
+ *
+ * ① 字面 hex 转义二次解析（2026-08-06 Kimi 首观察）：Kimi/deepseek 等网关会把 content 里的字面
+ *    "\x5Cx" / "\x5Cu" 当作 hex escape 再解释一遍，不足位时 400（"unexpected end of hex escape"）。
+ *    对策：不足位序列前 double 反斜杠（\\x5CxNN 形态还原为字面量）；合法完整序列放行。
+ *    Known limitation（2026-09-01 v3 修复）：反斜杠 run ≥3 时（如 "\\\x5Cu" 三反斜杠+u）v1 的
+ *    lookbehind 只看前 1 字符会整体放行，但二次解析按配对消费后尾部的 \x5Cu 仍裸露 → 炸。
+ *    修复：按 run 奇偶判断——run 为奇数时尾部的 \x5Cu/\x5Cx 裸露（需 double），偶数已配对（放行）。
+ *
+ * ② 孤立 UTF-16 代理对（2026-09-02 deepseek 真机实锤）：content 里的**真实孤立代理字符**
+ *    （高代理 U+D800-DBFF 无低代理跟随，或低代理 U+DC00-DFFF 无高代理前置）——JSON.stringify
+ *    输出 \ud83d（合法 JSON），但 deepseek 解析器严格 UTF-16 解码，孤立代理 → 400
+ *    （"unexpected end of hex escape" / "lone leading surrogate in hex escape"）。
+ *    来源实证：doc_search 结果预览 `slice(0, N)` 按 UTF-16 码元截断，emoji 🔴（代理对）恰在
+ *    截断边界被切成孤立高代理 → 注入 system reminder → 每轮发送 → deepseek 400。
+ *    对策：发送前把孤立代理替换为  U+FFFD（任何来源安全兜底）；源头截断点另修 UTF-16 安全切。
+ */
+
+/** 中和非法字面 hex 转义序列（毒源①）。 */
+export function escapeLiteralEscapes(text) {
+  text = String(text ?? "")
+  let out = ""
+  let i = 0
+  const n = text.length
+  while (i < n) {
+    const ch = text[i]
+    if (ch !== "\\") { out += ch; i++; continue }
+    // 数反斜杠 run 长度
+    let run = 0
+    while (i + run < n && text[i + run] === "\\") run++
+    const next = text[i + run]
+    if ((next === "x" || next === "u") && run % 2 === 1) {
+      // run 奇数 → 二次解析配对消费后尾部 \x5Cx/\x5Cu 裸露——hex 不足则网关炸 → 前插反斜杠 double
+      const need = next === "u" ? 4 : 2
+      const after = text.slice(i + run + 1, i + run + 1 + need)
+      if (!new RegExp(`^[0-9a-fA-F]{${need}}$`).test(after)) {
+        out += "\\".repeat(run + 1) + next
+        i += run + 1
+        continue
+      }
+      // 合法完整：输出全序列并跳过（hex 尾不重新扫描）
+      out += text.slice(i, i + run + 1 + need)
+      i += run + 1 + need
+      continue
+    }
+    out += "\\".repeat(run)
+    i += run
+  }
+  return out
+}
+
+/** 净化孤立 UTF-16 代理对（毒源②）：高代理无低代理跟随 / 低代理无高代理前置 → 替换为 。 */
+export function sanitizeLoneSurrogates(text) {
+  text = String(text ?? "")
+  let out = ""
+  let i = 0
+  const n = text.length
+  while (i < n) {
+    const cp = text.charCodeAt(i)
+    if (cp >= 0xd800 && cp <= 0xdbff) {
+      const next = text.charCodeAt(i + 1)
+      if (next >= 0xdc00 && next <= 0xdfff) { out += text[i] + text[i + 1]; i += 2; continue }
+      out += ""; i++; continue // 孤立高代理
+    }
+    if (cp >= 0xdc00 && cp <= 0xdfff) { out += ""; i++; continue } // 孤立低代理
+    out += text[i]; i++
+  }
+  return out
+}
+
+/** 发送前文本净化总入口：hex 转义中和 + 孤立代理净化。 */
+export function sanitizeText(text) {
+  return sanitizeLoneSurrogates(escapeLiteralEscapes(text))
+}
+
+/** 对单条消息的 content 应用 sanitizeText（支持字符串或 OpenAI 多模态 part 数组）。
+ *  2026-08-31 会诊 F5：deepseek-v4-flash 网关对 tool_calls[].function.arguments 与
+ *  reasoning_content 做同样的非标二次转义解析（字面 \\x5Cx/\\x5Cu 经工具参数/思考回传 → 400，
+ *  列号确定性复现 = 毒序列在 content 之外）——这两个字符串字段同样需要中和。 */
+export function escapeMessageContent(message) {
+  const content = message?.content
+  let changed = false
+  let next = message
+  if (typeof content === "string") {
+    const escaped = sanitizeText(content)
+    if (escaped !== content) {
+      next = { ...next, content: escaped }
+      changed = true
+    }
+  } else if (Array.isArray(content)) {
+    const parts = content.map((p) => {
+      if (p && typeof p === "object" && p.type === "text" && typeof p.text === "string") {
+        const escaped = sanitizeText(p.text)
+        if (escaped !== p.text) {
+          changed = true
+          return { ...p, text: escaped }
+        }
+      }
+      return p
+    })
+    if (changed) next = { ...next, content: parts }
+  }
+  if (Array.isArray(next.tool_calls)) {
+    let tcChanged = false
+    const tool_calls = next.tool_calls.map((tc) => {
+      const args = tc?.function?.arguments
+      if (typeof args === "string") {
+        const escaped = sanitizeText(args)
+        if (escaped !== args) {
+          tcChanged = true
+          return { ...tc, function: { ...tc.function, arguments: escaped } }
+        }
+      }
+      return tc
+    })
+    if (tcChanged) {
+      next = { ...next, tool_calls }
+      changed = true
+    }
+  }
+  if (typeof next.reasoning_content === "string") {
+    const escaped = sanitizeText(next.reasoning_content)
+    if (escaped !== next.reasoning_content) {
+      next = { ...next, reasoning_content: escaped }
+      changed = true
+    }
+  }
+  return changed ? next : message
+}
+
+/** IKBGX4 + SESSION.md §6.9：剥离仅本地使用的整消息标记字段（transient/ts）——发送给 provider 前移除。
+ * 严格 OpenAI 兼容服务端（opencode/LiteLLM 等）会拒绝消息级未知 key
+ * （"Extra inputs are not permitted, field: 'messages[i].transient'"）；ts 同理
+ * （消息时间戳是本地取证字段，不进任何 provider 请求——T-S3）。copy-on-write：
+ * 历史里的原对象不动（read_history 仍能读到 ts）。 */
+export function stripLocalMessageFields(messages) {
+  return messages.map((m) => {
+    if (m && typeof m === "object" && ("transient" in m || "ts" in m)) {
+      const { transient, ts, ...rest } = m
+      return rest
+    }
+    return m
+  })
+}
+
+/** 对整个 messages 数组逐条应用 escapeMessageContent（先剥离本地字段，再转义）。 */
+export function escapeMessages(messages) {
+  return stripLocalMessageFields(messages).map(escapeMessageContent)
+}

package/expand-home.mjs

@@ -0,0 +1,16 @@
+/**
+ * expand-home.mjs — 配置路径字段家目录展开器（第 29 批 HOME-EXPANSION，2026-09-11）。
+ * `loadConfig()` 单一规范化点（设计 MEMORY.md §9.3a）：纯函数、零依赖、home 可注入。
+ */
+
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+/** 展开配置路径字段的前缀 `~`（`~` / `~/` / `~\`）为主目录绝对路径；不识别形态原样返回。
+ *  home 第二参 = 测试注入缝（生产缺省 homedir()）。 */
+export function expandHome(p, home = homedir()) {
+  if (typeof p !== "string" || !p.startsWith("~")) return p   // 非字符串 / 非 ~ 前缀 → 原样
+  if (p === "~") return home                                  // 裸 ~ = 主目录
+  if (p[1] !== "/" && p[1] !== "\\") return p                 // ~user 等非分隔符 → 原样（不猜用户）
+  return join(home, p.slice(2).replaceAll("\\", "/"))         // 余段分隔符归一（跨端统一）
+}

package/explore-distill.mjs

@@ -0,0 +1,152 @@
+/**
+ * explore-distill.mjs — End-of-run exploration distillation (AGENT-LOOP §13 +
+ * CONTEXT-COMPACTION §6.9 H1, 2026-08-23). 2026-09-05 module-split: moved verbatim out of
+ * context.mjs (524 > 500 hard limit). The main agent's machine line is flooded by inline
+ * step-by-step exploration (read/grep/...). At run end we distill THIS run's exploration
+ * tool-results into one semantic summary note that replaces them in the machine line,
+ * while agent._fullHistory (the human line) stays untouched. Call form = session continuation
+ * (prefix reuse · §6.15): system + `history[0, lastBlockEnd)` verbatim messages + one tail
+ * instruction — built by the single-source constructor compress-form.mjs#buildCompressMessages
+ * (no second builder · D2); the declaration face (systemPrompt / tools) rides `extras` from the
+ * call point, same source as the turn request. VS Code adapter = thincoder-vscode/src/explore-distill.mjs.
+ */
+
+import { chat } from "./provider/index.mjs"
+import { buildCompressMessages } from "./compress-form.mjs"
+
+/** Read-only knowledge tools counted as "exploration" (execute writes files → never exploration). */
+export const EXPLORE_TOOLS = new Set([
+  "read", "grep", "glob", "ls", "code_search", "doc_search", "repo_outline",
+])
+
+/** Summary prompt for turning a burst of exploration results into a semantic summary. */
+export const EXPLORE_SUMMARY_PROMPT = `You are distilling exploration tool results. Summarize the following read-only codebase exploration into a compact semantic summary for the main agent's own context.
+
+Requirements:
+- Capture WHAT was discovered, WHERE (which files / directories / symbols), and the KEY CONCLUSIONS — do not list tool calls mechanically
+- Keep actionable facts the main agent needs to continue: code locations, function names, file paths, structure, and open questions the exploration raised
+- Drop raw tool-output noise, repeated lines, and verbatim file dumps — keep only what must be remembered
+- Be honest: mark anything not actually verified as "unverified"; do not present guesses as facts
+- Use bullet points; aim for information completeness, not a hard word limit
+
+Exploration log:
+`
+
+/** tool_calls name across both stored shapes ({function:{name}} and flat {name}). */
+function toolCallName(tc) {
+  return tc?.function?.name ?? tc?.name ?? ""
+}
+
+/** Tool that produced a tool-result message (falls back to its owner assistant's tool_call). */
+function toolResultName(msg, ownerToolCalls) {
+  if (typeof msg?.name === "string" && msg.name) return msg.name
+  const owner = (ownerToolCalls ?? []).find((tc) => tc.id === msg?.tool_call_id)
+  return owner ? toolCallName(owner) : ""
+}
+
+/**
+ * Find the pure-exploration "assistant(tool_calls)→tool…" pair blocks added since `start`.
+ * A block is explorable only when EVERY tool call AND every tool result in it is an exploration
+ * tool — mixed blocks (read + edit in one turn) stay untouched, or we'd orphan the edit pairing.
+ */
+function findExplorationBlocks(history, start) {
+  const blocks = []
+  let i = start
+  while (i < history.length) {
+    const m = history[i]
+    if (m?.role === "assistant" && Array.isArray(m.tool_calls) && m.tool_calls.length > 0) {
+      let j = i + 1
+      while (j < history.length && history[j]?.role === "tool") j++
+      const toolMsgs = history.slice(i + 1, j)
+      const allCallsExplore = m.tool_calls.every((tc) => EXPLORE_TOOLS.has(toolCallName(tc)))
+      const allResultsExplore = toolMsgs.length > 0 && toolMsgs.every((t) => EXPLORE_TOOLS.has(toolResultName(t, m.tool_calls)))
+      if (allCallsExplore && allResultsExplore) {
+        blocks.push({ start: i, end: j, messages: history.slice(i, j), toolCount: toolMsgs.length })
+      }
+      i = j
+    } else {
+      i++
+    }
+  }
+  return blocks
+}
+
+/**
+ * Core (shared) distillation: replace this run's pure-exploration pair blocks with a single
+ * "[Exploration summary]" note placed where the first block was. Returns a NEW history array,
+ * or null when there is nothing to shrink (<3 exploration results / LLM failure). Pairing-safe:
+ * whole assistant→tool blocks are removed, so no orphan tool_calls/tool can survive.
+ */
+async function distillExplorations(history, start, provider, signal, agent, depth, extras) {
+  if (!Array.isArray(history) || history.length - start < 2) return null
+  const blocks = findExplorationBlocks(history, start)
+  const resultCount = blocks.reduce((n, b) => n + b.toolCount, 0)
+  if (resultCount < 3) return null
+
+  // 切点 = 本 run 末块的 `end`（与替换面同一 blocks 数组——不新增第二处切割判据）。请求前缀 =
+  // tools 声明 + system + `[0, lastBlockEnd)`——皆回合请求已建缓存面（§6.15）；未命中面 =
+  // 尾部指令一条（+ ≤255 块对齐残余）。
+  const cut = blocks.at(-1).end
+
+  let summary
+  try {
+    // Silent by design (D11): thinking:null and no onToken/onReasoning — this internal
+    // distillation must not stream to the frontend. signal propagates user cancellation.
+    // 会话续写形态（§6.15 / D-CC21）：messages 由单源构造器 buildCompressMessages 产出（不设第二构造
+    // 点）；tools 取与回合请求同一声明面（**不带** tool_choice——实测该参数使服务端丢弃 tools 区）；
+    // 不覆盖 reasoningEffort ⇒ 与回合侧同源（v3 形态）。extras 缺省 ⇒ 退化面 1（无 system / 无 tools）。
+    const resp = await chat({ ...provider, thinking: null }, {
+      messages: buildCompressMessages(history, cut, extras?.systemPrompt, EXPLORE_SUMMARY_PROMPT),
+      tools: extras?.tools,
+      signal,
+      // §18.6 D-TR4：轨迹元数据增补——kind=distill（探索蒸馏面——agent 元数据透出；
+      // depth 经 summarizeRunExplorations 参数透传——agent.mjs 主作用域传入）
+      logCtx: {
+        stage: "distill", child: agent?._logId ?? null, kind: "distill",
+        role: agent?._role ?? null, depth: depth ?? null,
+        session: agent?._sessionStart ?? null, cwd: agent?.cwd ?? process.cwd(),
+        traces: agent?.config?.traces?.enabled !== false,
+      },
+    })
+    summary = resp?.content
+  } catch {
+    return null // N3: never block the run's return or lose history — original results stay
+  }
+  if (!summary) return null
+
+  const drop = new Set()
+  for (const b of blocks) for (let k = b.start; k < b.end; k++) drop.add(k)
+  const note = { role: "user", content: "[Exploration summary]\n" + summary }
+  const next = []
+  let inserted = false
+  for (let k = 0; k < history.length; k++) {
+    if (drop.has(k)) {
+      if (!inserted) { next.push(note); inserted = true }
+      continue
+    }
+    next.push(history[k])
+  }
+  return next
+}
+
+/**
+ * End-of-run exploration distillation (runAgent's final return). Shrinks the MACHINE line
+ * (agent.history) only; agent._fullHistory is never touched. Triggers when this run added ≥3
+ * exploration tool results; on LLM failure it silently keeps the original history (N3).
+ * The distillation itself is silent and never streams (D11); `callbacks.onDistilled` fires
+ * ONLY after the replacement actually lands (never on no-op/failure) — callers persist the
+ * compressed session (SEND-STALL-DISTILL §2.3).
+ * `extras` = 前缀面（{ systemPrompt, tools }——调用点透传、与回合请求同源 · §6.15）；缺省 ⇒ 退化面 1。
+ */
+export async function summarizeRunExplorations(agent, callbacks, signal, depth = 0, extras) {
+  const next = await distillExplorations(agent.history, agent._runStartHistoryLen ?? 0, agent.provider, signal, agent, depth, extras)
+  if (!next) return
+  agent.history = next
+  // The machine line changed shape — the measured token baseline was for the pre-shrink context.
+  // Invalidate so the next compaction check re-estimates instead of over-counting stale history.
+  agent._lastPromptTokens = null
+  agent._usageAtLen = null
+  // The compressed machine line must reach the disk: the run's own save already happened,
+  // so without this hook the async distill would leave the session un-compressed on exit.
+  callbacks.onDistilled?.()
+}