@thincoder/core 0.9.4 → 0.10.1

package/agent-tools/verify.mjs

@@ -11,11 +11,13 @@
  * path (doc-only changes return early) — the task list and self-review checklist.
  */
 
-import { isCodePath, isDocPath, loadConventions } from "../conventions.mjs"
+import { isCodePath, isDocPath, loadProjectDeclaration } from "../conventions.mjs"
 // #96（信息段与执行方式按端注入——CORE-UNIFICATION §2.13.4）：git / node --check 执行
 // 全部经核内执行面单点（默认径 = execFileSync 等价——CLI 语义零行为变；端侧 injected ⇒
 // 可中断执行器）；编辑器诊断段经 `configureVerifyDiagnostics` 注入（缺省不注入）。
 import { runCommand } from "../tools/exec-run.mjs"
+// #15 描述外置：描述文本单点 = tool-docs/verify.md（DESC 单解析面，缺档抛错语义不变）
+import { DESC } from "../tools/shared.mjs"
 import { existsSync } from "node:fs"
 import { resolve } from "node:path"
 
@@ -34,7 +36,7 @@ export function configureVerifyDiagnostics(impl) {
 export function resetVerifyDiagnostics() { injectedDiagnostics = null }
 
 /**
- * §18.12 D-VR1 path normalization — mirrors the §20.5 file-domain handling:
+ * D-VR1 path normalization — mirrors the file-domain handling (AGENT-LOOP-SUBAGENT.md §6.9):
  * resolved to an absolute path with forward slashes; dedup uses the win32
  * lowercase comparison key (changedFileKey) so "D:/x/src/a.mjs" and
  * "d:\\x\SRC\a.mjs" count as the same file.
@@ -74,28 +76,27 @@ function appendBlockGuidance(lines, codeFiles) {
  */
 export const verifyTool = {
   name: "verify",
-  description:
-    "Generic pre-completion verification gate — language/framework/project agnostic. verify does NOT run any test/verification command for you and does NOT require a test per change. You DECLARE your verification status via the verification argument: { status: 'passed' | 'failed' | 'skipped', command?, summary? }. 'passed' → allowed; 'failed' → blocked (cannot claim done); 'skipped' → allowed but requires a summary reason. Whether/how to verify is described in natural language in the project's AGENTS.md and is decided + executed by you — verify only mechanically gates on your declaration. Also reports changed files (git diff), an advisory node --check hint on changed .js/.mjs (not gating), the task list, and a self-review checklist. Call this BEFORE declaring a coding task complete — do not say 'done' until verify passes.",
+  description: DESC("verify"),
   parameters: {
     type: "object",
     properties: {
       verification: {
         type: "object",
-        description: "The model's declaration of whether it already ran the project's verification and its outcome. verify does not execute the command — it is self-reported evidence.",
+        description: "Your declaration of whether you already ran the project's verification and its outcome — self-reported evidence (verify does not execute the command).",
         properties: {
           status: { type: "string", enum: ["passed", "failed", "skipped"], description: "The verification outcome you declare: 'passed' → allowed; 'failed' → blocked; 'skipped' → allowed but requires a summary reason." },
-          command: { type: "string", description: "Optional: the verification command you ran (self-reported — verify does not execute it)." },
-          summary: { type: "string", description: "Optional: summary/result of the verification. Required when status='skipped' — a concrete reason (e.g. \"project has no automated tests — verified by manual review\")." },
+          command: { type: "string", description: "Optional: the verification command you ran (self-reported)." },
+          summary: { type: "string", description: "Optional: the result. Required when status='skipped' — a concrete reason (e.g. \"project has no automated tests — verified by manual review\")." },
         },
         required: ["status"],
       },
-      workdir: { type: "string", description: "Optional: run verify in this subdirectory (relative to cwd or absolute) — for monorepos" },
+      workdir: { type: "string", description: "Optional: run verify in this subdirectory (relative to cwd or absolute) — monorepos" },
     },
   },
   readonly: true,
   async execute(args, ctx) {
     const cwd = ctx.agent.cwd
-    // Changed-file resolution (§18.12 D-VR3): _touchedFiles (per-run bookkeeping,
+    // Changed-file resolution (D-VR3): _touchedFiles (per-run bookkeeping,
     // absolute paths) ∪ git diff fallback — git is tried at testCwd
     // (workdir-resolved) first, then at ctx.agent.cwd; first success wins.
     // git-diff paths are repo-root-relative — resolved against the discovered
@@ -105,7 +106,7 @@ export const verifyTool = {
     lines.push("=== VERIFICATION REPORT ===")
     lines.push("")
 
-    // 1. Changed files — _touchedFiles ∪ git diff (§18.12 D-VR1)
+    // 1. Changed files — _touchedFiles ∪ git diff (D-VR1)
     let gitOk = false
     let gitStat = ""
     let gitFiles = []
@@ -131,7 +132,7 @@ export const verifyTool = {
       lines.push("Changed files: (not a git repo or git unavailable)")
     }
     // _touchedFiles: files written by the tools this run — captured regardless
-    // of git state (§18.12 F-VR1: subagent cwd ≠ git root must still locate).
+    // of git state (F-VR1: subagent cwd ≠ git root must still locate).
     const touchedFiles = (ctx.agent._touchedFiles ?? []).map((p) => normalizeChangedPath(p, cwd))
     const gitKeys = new Set(gitFiles.map(changedFileKey))
     const touchedOnly = touchedFiles.filter((p) => !gitKeys.has(changedFileKey(p)))
@@ -173,10 +174,10 @@ export const verifyTool = {
     // for doc changes, and the task list/self-review checklist add nothing either.
     // Paths inside a declared code segment (default: src — incl. prompts/*.md) are
     // product code — excluded from the fast path, consistent with the design gate.
-    // The project's own layout is declarable (.thincoder/conventions.json).
+    // The project's own layout is declarable (the manifest's codePaths).
     // Empty list (no changes / git unavailable)
     // intentionally falls through to the normal path below.
-    const conv = loadConventions(cwd)
+    const conv = loadProjectDeclaration(cwd)
     if (changedFiles.length > 0 && changedFiles.every((f) => isDocPath(f, conv))) {
       lines.push("")
       lines.push("Documentation-only changes — skipping syntax checks and tests.")

package/agent-tools.mjs

@@ -21,7 +21,6 @@ export { batchTool } from "./agent-tools/batch.mjs"
 // 批次档生命周期工具（BATCH-RECORD §4.3 挂载表——主名 `batch` 单工具四 action：depth-0 主 agent
 // create/close + append §1/§4/§6 + status §1（轮 2 裁定②：§4/§6 状态面走普通文档写）（D-BR18）；
 // eng 子代理 eng 分支绑定段写入；评审 §3。
-// 过渡别名 batchSegmentTool 不入登记册（§4.14——生产挂载面全切主名；别名仅供 shim 导出面）。
 // CORE-UNIFICATION TOOLS #83（统一登记册——VSC `agent-tools/index.mjs:15` 含 consult 家族；
 // CLI 原把 consult 另挂 `agent/setup.mjs:173` ⇒ 归位：登记册即单一来源，装配方只读本档）。
 export { consultStartTool, consultStopTool } from "./agent-tools/consult.mjs"

package/agent.mjs

@@ -2,33 +2,22 @@
  * agent.mjs — Agent main loop
  * LLM ↔ tool-call loop, until the task is done.
  */
-import { chat } from "./provider/index.mjs"
-import { abortError, annotateAbort } from "./abort-provenance.mjs"
-import { pushReal, summarizeRunExplorations } from "./context.mjs"
-import { specForModel, assistantToolCallMessage } from "./config.mjs"
-import { resolve } from "node:path"
-import { executeToolCalls } from "./agent/dispatch.mjs"
-import { recordToolResults } from "./agent/record-results.mjs"
-import { FILE_MUTATORS } from "./agent/helpers.mjs"
-import { prepareRun } from "./agent/setup.mjs"
-import { injectPostTurn } from "./agent/post-turn.mjs"
-import { handleCompletion } from "./agent/completion.mjs"
 // PROMPT-SYSTEM 施工② G1（2026-09-10）：六件槽位常量装载收口 prompt-overlays.mjs
 // （与子代理角色常量同源——单一权威锚 D1）；旧三件文件读取随本批退役。
 // 槽位常量通过下方 re-export 面（mod: rel — re-export 保 import 面）；本文件自身零直接消费。
 // 主循环阶段函数（压缩检查/注入组/回合收尾）2026-09-05 实践轮迁 agent/run-stages.mjs
-import { runCompactionCheck, injectTurnReminders, finalizeAgentTurn, injectResponseReminders } from "./agent/run-stages.mjs"
+// 2026-09-29 P2 三拆（#579）：起跑前段 ∕ 回合环 ∕ 模型调用逐字迁 agent/run-start.mjs ∕
+// agent/turn-loop.mjs ∕ agent/chat-call.mjs——本档残留 = 编排 + 状态工厂 + 面（re-export 保面）。
+import { beginRun } from "./agent/run-start.mjs"
+import { runTurnLoop } from "./agent/turn-loop.mjs"
+import { finalizeAgentTurn } from "./agent/run-stages.mjs"
 import {
-  escapeXml, repairHistory, listWorkDir,
+  escapeXml, listWorkDir,
   readonlyToolNames, collectGitContext, loadProjectInstructions,
   ContinueError,
-  turnFrame, // 第 19 批（TURN-ACROSS-SEGMENTS）：跨段累计编号帧（设计 §19.3）
   DEFAULT_MAX_TURNS, DEFAULT_SUBAGENT_TURNS,
   MIN_REPORT_CHARS, REPORT_CONTINUATION,
-  AUTO_TURN_DIGEST_DOMAIN,
-  AUTO_TURN_DIGEST_DOMAIN_ENG, // §6.15.3（F10 第三面）：工程模式 digest 基座变体（task 指针改批次档 + 台账）
-  UPSTREAM_TURN_DOMAIN, // §6.27.12.8：上行唤醒轮域文本（手动档——ask 轮不沿用 digest 域文本）
-  restoreGuard, // digest D-S6 读侧单点（AGENT-LOOP-ASYNC-POOL.md §6.8；P2 机制层端差批 §2.18——键清单归核）
+  SUBAGENT_TOOL_EXCLUSIONS, excludeSubagentTools, // TOOLS.md §6.16：子代面按面排除（helpers 单源）
 } from "./agent/helpers.mjs"
 // ENG 提醒族 + auto-turn domain 2026-09-05 迁 agent/helpers.mjs（agent.mjs 530 > 500 硬限）
 // PROMPT-SYSTEM 施工② G1（2026-09-10）：六件槽位常量装载收口 prompt-overlays.mjs
@@ -50,11 +39,14 @@ export {
   listWorkDir, loadProjectInstructions,
   readonlyToolNames, collectGitContext, escapeXml,
   MIN_REPORT_CHARS, REPORT_CONTINUATION, DEFAULT_SUBAGENT_TURNS,
+  SUBAGENT_TOOL_EXCLUSIONS, excludeSubagentTools, // TOOLS.md §6.16（子代装配点从本档取用）
 }
 
 
 // Re-exported for API compatibility (single source of truth: advisor/repos.mjs)
 export { hasCodeMutations } from "./advisor/repos.mjs"
+// 流式输出门（§2.5 #78）2026-09-29 P2 三拆随 agent/chat-call.mjs 迁出——re-export 保 import 面
+export { streamOutputAllowed } from "./agent/chat-call.mjs"
 
 /** Create a new agent state object with all fields initialized to defaults */
 export function createAgent({
@@ -73,8 +65,8 @@ export function createAgent({
     // (AC3 零写) — no field initializer; the multi-slot Map `_engDesignTokens` is the
     // authoritative ledger (hydrated by restoreEngTokens / written by settle).
     _touchedFiles: [], _verifyRetries: 0, _advisorRound: 0, _advisorSession: null,
-    _advisorRuns: new Map(), // §11.2 D-24b: per-review convergence instances (rounds/prior/designId)
-    _mutationSeq: 0, _mutLog: [], // §11.2 D-24b: mutation log (in-flight review staleness scan)
+    _advisorRuns: new Map(), // AGENT-LOOP-ASYNC-POOL.md §6.10 D-24b: per-review convergence instances (rounds/prior/designId)
+    _mutationSeq: 0, _mutLog: [], // AGENT-LOOP-ASYNC-POOL.md §6.10 D-24b: mutation log (in-flight review staleness scan)
     _lastAdvisorOutput: null, // full review output from the most recent advisor call (convergence rounds inject it verbatim)
     _lastEngState: false,
     _pendingReminders: [],
@@ -89,341 +81,18 @@ export function createAgent({
   }
 }
 
-/** 流式输出门（§2.5 #78 并入——VSC 三态门，纯函数可直驱测试）：depth 0 恒通；
- *  consult 子代理豁免（其输出进会诊面板）；其余经 `streamOutput` 显式选择进入。 */
-export function streamOutputAllowed(depth, role, streamOutput = false) {
-  return depth === 0 || role === "consult" || streamOutput === true
-}
-
 /** Run the agent loop: LLM ↔ tool-call cycle until task completion or turn limit. Returns final text content. */
-export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal, maxTurns: overrideTurns, resume = false, autoTurn = false, upstreamTurn = false, suspDriven = false, consumeInjected = null, streamOutput = false, extraTools = null } = {}) {
-  // Previous run's async exploration distillation must settle before this run pushes
-  // input (SEND-STALL-DISTILL §2.2 N1) — await first, or its history replace wipes it.
-  if (agent._pendingDistill) {
-    const p = agent._pendingDistill
-    agent._pendingDistill = null
-    await p
-  }
-  // §17 D-S3: suspension-settled async results inject before EVERY run's prepareRun
-  // (user + auto-turn); spliced = consumed. collectSettledAsync owns a different
-  // container, so no double-inject across the two consumption points.
-  // ASYNC-RESULT-CONTAINER.md D2 (2026-09-08)：pending 单容器 `_pendingAsyncResults`
-  // +role——四族（subagent/advisor/escalate/consult）统一停靠；注入器按 role 分发
-  // （consult → injectConsultResult；其余 → injectAsyncResult——族分支同 §25 D-R17a/b）
-  // ——单容器一处清，不再逐族三段。
-  const pendingAsync = agent._pendingAsyncResults
-  if (pendingAsync?.length) {
-    const { injectAsyncResult } = await import("./agent-tools/subagent.mjs")
-    const { injectConsultResult } = await import("./agent-tools/consult.mjs")
-    // TUI-OOM-ROOTCAUSE（AGENT-LOOP.md §23.3.1 消费点②——run 起始 pending 注入）：
-    // 注入完成后释放条目对子代理对象的持有（childAgent/report 置空——幂等 helper）。
-    const { releaseSettledEntry } = await import("./agent-tools/async-settle.mjs")
-    for (const e of pendingAsync.splice(0)) {
-      if (e.role === "consult") await injectConsultResult(agent, e)
-      else await injectAsyncResult(agent, e)
-      releaseSettledEntry(e)
-    }
-  }
-  agent._inAutoTurn = autoTurn // spawn gate for manual-tier digests (§17 D-S6/N3；上行唤醒轮同持 autoTurn——§6.27.12.4 ①)
-  const { maxTurns, threshold, tools, toolSchemas, toolByName, systemPrompt } = await prepareRun(
-    // G1/G2（施工②）：prompt 装配收口 prepareRun 内部（assemblePrompt——prompt-overlays.mjs
-    // 槽位常量，与子代理角色常量同源——单一权威锚 D1）；本调用不再携带 prompt 常量。
-    agent, input, callbacks,
-    { depth, signal, overrideTurns, resume: resume || autoTurn, extraTools },
-  )
-
-  // Exploration-distillation boundary (CONTEXT-COMPACTION §5): prepareRun already
-  // pushed input + injections — appended from here counts as "this run's" work.
-  agent._runStartHistoryLen = agent.history.length
-
-  // Per-run bookkeeping reset — PRESERVED on `resume` (ContinueError continuation):
-  // mutation/guard continuity and the convergence budget must survive a continuation.
-  if (!resume) {
-    // 第 19 批（TURN-ACROSS-SEGMENTS——设计 TURN-CAP-CONTINUE.md §19.3）：链内累计编号
-    // 只在链起点复位——续跑（resume:true）不重置、不回退（编号帧公式见 helpers.mjs
-    // turnFrame）。与下方 mutation/guard 复位同条件同点（全档唯一复位点）。
-    agent._turnSeq = 0
-    // §17 D-S6: an auto-turn's guard marks are inherited by the next USER run (not
-    // reset) so auto-turn changes never escape the guard silently.
-    const g = agent._inheritedGuard
-    if (g) {
-      restoreGuard(agent, g)
-      agent._inheritedGuard = null
-    } else {
-      agent._mutatedThisRun = false
-      agent._verifiedThisRun = false
-      agent._verifyPassed = undefined
-      agent._calledAdvisorThisRun = false
-      agent._touchedFiles = []
-      agent._verifyRetries = 0
-      agent._advisorRound = 0
-      agent._advisorSession = null // advisor session is per-run: discard when the task ends, next task starts fresh
-      agent._emptyRetries = 0 // empty-response retry budget is per-run: a fresh user turn restarts from zero
-      agent._compressFailures = 0 // compaction summary-failure counter is per-run: a fresh user turn restarts from zero
-      // F-CC2（§6.16.2）：模型主动压缩的排队槽也是回合级——上一回合末尾未被安全点消费的请求不得跨回合生效
-      agent._pendingCompact = null
-    }
-  }
-  // digest D-S6 manual tier（AGENT-LOOP-ASYNC-POOL.md §6.8）: action-domain reminder (system-driven turn — organize only).
-  // §6.27.12.4 ②: an up-stream wake turn answers a RUNNING subagent waiting for the reply — it
-  // must not reuse the digest text ("no one is waiting" is the opposite of the truth).
-  if ((autoTurn || upstreamTurn) && !agent.autoApprove) {
-    agent.history.push({ role: "user", content: upstreamTurn ? UPSTREAM_TURN_DOMAIN : (agent.config?.agent?.engineering === true ? AUTO_TURN_DIGEST_DOMAIN_ENG : AUTO_TURN_DIGEST_DOMAIN), transient: true })
-  }
-  // eng-coder authorization (_engDesignReviewed) is eng-coder-only: set by subagent-spawn.mjs
-  // (spawn gate) / design-token.mjs (design review pass) BEFORE the child runAgent — the
-  // depth-0 parent never reads or writes it (the parent gate reads anyLiveDesignSlot; the
-  // depth-0 per-turn reset was removed 2026-09-08, ENG-SESSION-PROVIDER-CLEANUP D1.3).
-  // Design slots (_engDesignTokens Map) survive across turns (design review → approval →
-  // eng-coder spawn) — persisted to the session slot at settle time (DESIGN-TOKEN-
-  // SETTLEMENT D1); lifecycle: issued on a passing review, consumed by consume-design / TTL.
-  let guardPushbacks = 0
-  let advisorPushbacks = 0
-  let honestReminderInjected = false
-  const recentCallSigs = []
-  // "once" stream rules fire at most once per runAgent call; the set survives across
-  // chat() calls (rule abort-retry, tool loop) within the turn.
-  const streamRuleFired = new Set()
-
-  // Compaction overhead for the pure-estimation path: system prompt + tools schema are
-  // in every request but not in history — without them the first-turn/just-compacted
-  // estimate under-counts and may never trigger. Measured path already includes both.
-  const compactionOverhead = {
-    systemPrompt,
-    tools: toolSchemas,
-    // §18.6 D-TR4：compress 轨迹 depth 元数据（runAgent 的 depth 在此作用域——
-    // context.mjs compressIfNeeded 经 extras 透出到 logCtx）
-    traceDepth: depth,
-  }
-  // F-CC1（§6.16.4 阈值单源接线）：本回合压缩判定所用的阈值 + 固定开销面暂存——
-  // `context` 工具的 stats 报**同一口径**（不自行重算第二口径；VSC checkAndCompact 同款暂存）。
-  agent._ctxBasis = { threshold, overhead: compactionOverhead }
-
-  // SUBAGENT-UPSTREAM-CHANNEL（AGENT-LOOP-UPSTREAM.md §6.27.4 消费点）：子 → 父在飞消息的
-  // 回合边界注入单点取用一次（模块缓存 ⇒ 每 run 一次代价）；动态 import = 零新增静态边
-  // （先例 = 上方 injectAsyncResult :113-117）。
-  const { drainChildUpstream } = await import("./agent-tools/parent-channel.mjs")
+export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal, maxTurns: overrideTurns, resume = false, autoTurn = false, upstreamTurn = false, timerTurn = false, suspDriven = false, consumeInjected = null, consumeQueuedInput = null, streamOutput = false, extraTools = null, injections = null, turnDomainText = null, distillSignal = null, toolDecorate = undefined } = {}) {
+  const { maxTurns, threshold, toolSchemas, toolByName, systemPrompt } = await beginRun(agent, input, callbacks, {
+    depth, signal, overrideTurns, resume, autoTurn, upstreamTurn, timerTurn, extraTools, injections, turnDomainText, toolDecorate,
+  })
 
   let thrownError = null
   try {
-    for (let turn = 0; turn < maxTurns; turn++) {
-    // 第 19 批（TURN-ACROSS-SEGMENTS——设计 TURN-CAP-CONTINUE.md §19.3）：编号帧——
-    // `_turnSeq` 每轮 +1（跨段累计，仅 `!resume` 链起点复位）；面向消费面的两字段
-    // （状态行 + ⟦ev⟧turn / ⟦ev⟧approval 事件共用）在此同点赋值（编号唯一权威；帧
-    // 公式 = helpers.mjs turnFrame）。段内帽判定不读帧（下行循环条件只读段内
-    // turn / maxTurns——N6）。
-    const frame = turnFrame(++agent._turnSeq, turn, maxTurns)
-    agent._currentTurn = frame.turn
-    agent._maxTurns = frame.maxTurns
-    // D2 (AGENT-LOOP.md §7.2): depth>0 children emit a ⟦ev⟧turn progress token each turn —
-    // single emit point covering all three spawn tools; phase=llm (tool/done progress rides
-    // the onToolCall/onToolResult relay — no token for those). 第 19 批：载荷取上方帧值
-    // （agent._currentTurn / _maxTurns——字段形态 / 字段数 / phase 零变化，N5）。
-    if (depth > 0 && callbacks.onToken) {
-      callbacks.onToken(`⟦ev⟧turn\x1e${agent._currentTurn}\x1e${agent._maxTurns}\x1ellm\x1e`)
-    }
-    // §2.5 #78 并入（VSC 帧回调）：每轮帧另经结构化回调发出（池条目 entry.turn 的
-    // VSC 等价通道——⟦ev⟧turn token 解析的宿主面随时可用；签名扩展向后兼容）。
-    callbacks.onAgentTurn?.(frame.turn, frame.maxTurns)
-
-    // SUBAGENT-OBSERVE-SEND D2: 子代理回合边界消费点——每轮开头把父侧经 subagent
-    // action:'send' 注入队列（entry._injected）的消息按普通 user 回合推入子历史
-    // （pushReal → 下一轮 chat 即含该指令）。由 executeAsyncSpawn 经 childRunOpts 贯通的
-    // consumeInjected 回调承载（异步子代理专属——缺省 null：主会话/阻塞子代理零开销）。
-    consumeInjected?.(agent)
-    // 子代理在飞消息（子 → 父；§6.27）：空队列 no-op；非空 ⇒ 恰一条合并 user 消息注入。
-    drainChildUpstream(agent)
-
-    const lastRole = agent.history.at(-1)?.role
-    if (lastRole === "user" || lastRole === "tool") {
-      // 2026-09-05 实践轮：压缩检查/降级计数提为 runCompactionCheck（agent/run-stages.mjs——
-      // CLI 对位 VS run-stages）——循环骨架此处只剩检查调用（recentCallSigs 对象引用回流）。
-      await runCompactionCheck(agent, { threshold, callbacks, compactionOverhead, signal, recentCallSigs })
-    }
-
-    // 2026-09-05 实践轮：plan cadence + eng 状态注入提为 injectTurnReminders（run-stages）
-    await injectTurnReminders(agent, { depth })
-
-    const messages = [{ role: "system", content: systemPrompt }, ...agent.history]
-    let response
-
-    // Auto-think: classify difficulty and set reasoning effort on turn 0; silent on failure.
-    if (agent.config?.agent?.autoThink && turn === 0) {
-      const { classifyAndApply } = await import("./auto-think.mjs")
-      await classifyAndApply(agent, turn).catch(() => {})
-    }
-
-    if (process.env.ADVISOR_DEBUG) console.error("[chat-call]", JSON.stringify({ turn, histLen: agent.history.length, lastRole: agent.history.at(-1)?.role }))
-    try {      response = await chat(agent.provider, {
-        messages, tools: toolSchemas,
-        // §2.5 #78 并入（VSC onToken 三态门）：depth 0 恒通；consult 子代理豁免（其输出进
-        // 会诊面板）；escalate 等经 opts.streamOutput 显式选择进入；其余子代理不流式。
-        onToken: streamOutputAllowed(depth, agent._role, streamOutput) ? callbacks.onToken : null,
-        onReasoning: callbacks.onReasoning,
-        onWait: callbacks.onWait,
-        signal,
-        streamRules: agent.config.agent?.streamRules ?? [],
-        firedPatterns: streamRuleFired,
-        // LOGGING（LOGGING.md）：llm:* 事件的语义上下文（stage=turn 主循环回合——含
-        // digest 消化轮 auto=true；child=子代理 id（spawn 时 stamp 于 child._logId））
-        // §18.6 D-TR4：轨迹元数据增补（role/depth/kind/session/cwd——trace-store 只读
-        // logCtx，签名不变）；kind：depth>0 = subagent（consult 孩子 = consult）——子代理
-        // 对回靠 role+depth+child id（children 无 _sessionStart——不经 depth-0 设置——
-        // session 字段对子代理轨迹为 null——见 trace-store/agent.mjs 注释）。
-        logCtx: {
-          stage: "turn", turn: turn + 1, auto: autoTurn, child: agent._logId,
-          role: agent._role ?? null,
-          depth,
-          kind: depth > 0 ? (agent._role === "consult" ? "consult" : "subagent") : "turn",
-          session: agent._sessionStart ?? null,
-          cwd: agent.cwd,
-          traces: agent.config?.traces?.enabled !== false,
-        },
-      })
-    } catch (e) {
-      // User interrupt (Ctrl+I): controller.abort({ interrupt: true, message }).
-      // Inject into history; the outer loop recreates the controller and resumes.
-      if (e.name === "AbortError" && signal?.reason?.interrupt) {
-        const msg = `[User interrupt: ${signal.reason.message}]`
-        // Dedup: if already handled during tool execution (interrupt branch below),
-        // don't push a duplicate — the outer loop still recreates the controller.
-        if (agent.history.at(-1)?.content !== msg) {
-          agent.history.push({ role: "user", content: msg })
-        }
-      }
-      throw e
-    }
-
-    // 内置工具（Responses web_search）结果本地化：服务端已执行——入历史为 tool 消息；
-    // 服务端 item id 是 msg_xxx 非 web_search_call_ 前缀——必须合成前缀（toItems 识别锚点），
-    // 原始 id 存入 content（真机冒烟 2026-08-31 验证）。
-    for (const btr of response.builtinToolResults ?? []) {
-      if (!btr?.id) continue
-      pushReal(agent, {
-        role: "tool",
-        tool_call_id: `web_search_call_${btr.id}`,
-        content: JSON.stringify({ id: btr.id, query: btr.query ?? "", sources: btr.sources ?? [], status: btr.status ?? "completed" }),
-      })
-    }
-
-    // Stream rule triggered mid-generation (action: "abort"): halt, inject the rule's
-    // message as a reminder, retry from the same context.
-    if (response.ruleTriggered) {
-      if (response.content) {
-        pushReal(agent, { role: "assistant", content: response.content })
-      }
-      const label = response.ruleName ? ` — stream rule "${response.ruleName}"` : ""
-      agent.history.push({
-        role: "user",
-        content: `[System reminder${label}: ${response.ruleMessage}]`,
-      })
-      continue
-    }
-
-    // Stream rule warnings / finish-reason 警告（2026-09-05 实践轮——提为
-    // injectResponseReminders，agent/run-stages.mjs——verbatim，语义零变）
-    injectResponseReminders(agent, response)
-
-    // User interrupted mid-generation (Ctrl+I): commit partial output + inject the
-    // message, then signal the outer loop to recreate the controller and resume.
-    if (response.interrupted) {
-      if (response.content) {
-        pushReal(agent, { role: "assistant", content: response.content })
-      }
-      agent.history.push({
-        role: "user",
-        content: `[User interrupt: ${response.interruptMessage}]`,
-      })
-      // §20.3 站点 #8（第 24 批）：错误对象已自带 name/message——只补来源标注（缺 abortInfo 才补）
-      throw annotateAbort(Object.assign(new Error("User interrupted"), { name: "AbortError" }), signal, "agent", "interrupted-response")
-    }
-
-    if (response.usage) {
-      callbacks.onUsage?.(response.usage)
-      if (response.usage.prompt_tokens != null) {
-        agent._lastPromptTokens = response.usage.prompt_tokens
-        agent._usageAtLen = agent.history.length
-      }
-    }
-
-    // Warn on abnormal finish reasons — the response may be incomplete/truncated.
-    // 2026-09-05 实践轮：finish-reason 注入随流规则警告提为 injectResponseReminders。
-
-    if (response.toolCalls.length === 0) {
-      const cr = handleCompletion(agent, response, depth, turn, guardPushbacks, honestReminderInjected, advisorPushbacks, callbacks)
-      guardPushbacks = cr.guardPushbacks
-      honestReminderInjected = cr.honestReminderInjected
-      advisorPushbacks = cr.advisorPushbacks
-      if (cr.action === "continue") continue
-      if (depth === 0) {
-        // End-of-run exploration distillation (CONTEXT-COMPACTION §5 + SEND-STALL-DISTILL
-        // §2.1): async — the promise hangs on _pendingDistill, settling at the next run's
-        // start or the TUI exit flush. Silent (N3): failure never blocks return/history.
-        // §18.6 D-TR4：depth 透传（distill 轨迹元数据——与 compress 同通道）；extras = 会话续写前缀面（§6.15）
-        const distill = summarizeRunExplorations(agent, callbacks, signal, depth,
-          { systemPrompt, tools: toolSchemas }).catch(() => {}) // 与回合请求同源（无第二构造点）
-        agent._pendingDistill = distill
-      }
-      return cr.content
-    }
-
-    // abort after chat completes, before committing history: don't commit a half-finished turn
-    if (signal?.aborted) throw abortError(signal, "agent", "post-chat")
-
-    pushReal(agent, assistantToolCallMessage(response, specForModel(agent.provider.model)))
-
-    const results = await executeToolCalls(agent, toolByName, response.toolCalls, callbacks, depth, signal)
-
-    // Ctrl+I interrupt during tool execution: skip committing partial results — inject
-    // the interrupt and retry (placeholder results keep strict providers pairable).
-    if (signal?.reason?.interrupt) {
-      // 中断变更记账（2026-08-31 评审 #4）：此分支的工具已全部执行完成（磁盘已变，execute 已完成），
-      // 真实结果按语义不进历史（placeholder 替代）——但变更必须记账：否则 guard 看到
-      // "本轮未改代码" 放行，评审/verify 门禁被绕过（文件改了却没评审）。
-      // §29 fix A（2026-09-07）：mutation-seq 记账已收敛到 dispatch runOne 执行成功即刻
-      // （唯一记账点——本分支不再 noteMutations——不双计——中断+同批 launch seq 单计
-      // 回归断言见 §29 T-A1i）；此处仅剩 guard 标志 + touchedFiles 记账。
-      for (const { toolCall, ok } of results) {
-        const tool = toolByName.get(toolCall.name)
-        if (!ok || !tool || !FILE_MUTATORS.has(toolCall.name)) continue
-        agent._mutatedThisRun = true
-        agent._calledAdvisorThisRun = false
-        agent._verifiedThisRun = false
-        agent._verifyPassed = undefined
-        try {
-          const args = JSON.parse(toolCall.arguments)
-          const paths = tool.touchedPaths ? tool.touchedPaths(args) : [args.path]
-          for (const p of paths) {
-            const abs = resolve(agent.cwd, p)
-            if (!agent._touchedFiles.includes(abs)) agent._touchedFiles.push(abs)
-          }
-        } catch { /* 畸形 args 不影响记账（touchedFiles 尽力而为） */ }
-      }
-      // The assistant tool_calls were committed above — synthesize placeholder tool
-      // results BEFORE the interrupt message (strict providers 400 on dangling
-      // tool_calls; consult P1, 2026-08-30).
-      for (const tc of response.toolCalls) {
-        agent.history.push({ role: "tool", tool_call_id: tc.id, content: "[Tool execution interrupted — results discarded]" })
-      }
-      agent.history.push({
-        role: "user",
-        content: `[User interrupt: ${signal.reason.message}]`,
-      })
-      callbacks.onTurnEnd?.(agent, turn)
-      continue
-    }
-
-    // Model is executing tools → real work: reset guard pushback counters
-    guardPushbacks = 0
-    advisorPushbacks = 0
-
-    // Commit tool results (pairing, multimodal deferral, mutation accounting, reindex)
-    await recordToolResults(agent, toolByName, results)
-
-    injectPostTurn(agent, results, recentCallSigs, callbacks, turn)
-    }
-
-    throw new ContinueError(maxTurns)
+    return await runTurnLoop(agent, {
+      maxTurns, threshold, toolSchemas, toolByName, systemPrompt,
+      depth, signal, autoTurn, streamOutput, consumeInjected, consumeQueuedInput, callbacks, distillSignal,
+    })
   } catch (e) {
     thrownError = e
     throw e

package/attachments.mjs

@@ -0,0 +1,125 @@
+/**
+ * attachments.mjs — 回合附件（粘贴图）族：dataURL 解析 ∕ 临时落盘管线 ∕ 非多模态降级
+ * （上提核件 —— 处理流批 R5 · 2026-09-28）。
+ *
+ * 上提源（迁移前坐标）= VSC `thincoder-vscode/src/extension/image-handler.mjs`（`parseDataUrl` :34 ·
+ * `savePastedImages` :49 · `downgradeNonVisionImages` :109）；预算语义（合计 30MB ∕ 轮 · 溢出项弃后
+ * **继续扫**「其余照发」）与配额单位 = 桌面同档 `thincoder-desktop/src/main/attachments.mjs`
+ * （15MB ∕ 条 —— 与核 `read_image` 内闸同值同单位：`tools/file.mjs:26` `MAX_IMAGE_BYTES = 15_000_000`，
+ * 接纳面不得宽于该闸）。本档 = 单源（消费面 = 桌面 `src/main/attachments.mjs`；VSC 自持副本已随本批（parity-b4）迁移改指本档）。
+ * 指引行（`[Attached images: …]`）不迁 —— 单源 = `agent/setup-reminders.mjs:248` `appendImagePointer`（原位）。
+ *
+ * 与 VSC 自持副本的在册差异（双写窗口）**收正已毕**（迁移轮 parity-b4 —— 逐条处置见批档 §2.3）：① 阈单位 ∕
+ * ② 弃项索引 ∕ ③ 合计预算闸 ∕ ④ 降级成功判据 = **两端同源单值**（收正方向——VSC 侧本地字面 ∕ 过滤后下标 ∕ 无预算 ∕
+ * 真值判四面随迁移删；VSC 消费本档 `IMAGE_MAX_BYTES` ∕ 源序命名 ∕ `TURN_MAX_BYTES` ∕ `out.ok !== true`）；
+ * ⑤ 清理面 = **端侧时序面**（本档不回收）：桌面 = 逐回合显式清（`cleanupTurn`——仅删本回合在册路径；
+ * 半失败写入的孤儿件无回收面〔此判仅桌面面成立〕）· CLI ∥ VSC = 贴图落盘写时 mtime 扫除
+ * （3 天窗——目录内超龄件（含孤儿件）按龄回收）；机制单源 = `docs/core/design/PROVIDER.md` §6.18。
+ *
+ * 两面 + 两缝：
+ *  ① 落盘管线（`savePastedImages`）：逐项解析 ⇒ 预算判 ⇒ 写 `<cwd>/.thincoder/tmp/paste-<id>-<i>.<ext>`
+ *     （懒建目录；建面 ∕ 写面运行时失败 ⇒ 该项弃 + 一次诊断 —— 皆不阻断发送）。**fs 写转注入缝**
+ *     （`fs = { mkdirSync, writeFileSync }` —— `node:fs` 同名面；本档零 `node:fs`）。
+ *  ② 非多模态降级（`downgradeNonVisionImages`）：判据 = 图非空 ∧ 模型在场 ∧ 非多模态
+ *     （`isNonVisionModel`）⇒ 读图；成功 ⇒ 描述注文（`[图片 … 描述: …]`）+ 图清空；
+ *     失败 ⇒ 原样兜底（不静默丢）。**视觉子代理 spawn 转注入缝**（`visionReader({ paths, signal })` ——
+ *     缺省实现 = 核 `vision-reader.mjs` `runVisionReader`（桌面径直取）；VSC 经宿主包装注入）。
+ */
+import { join } from "node:path"
+import { specForModel } from "./model-specs.mjs"
+
+/** 单项上限 15MB（与 `read_image` 内闸同值同单位 —— `tools/file.mjs:26` `MAX_IMAGE_BYTES = 15_000_000`：
+ *  超阈件交核也读不进 ⇒ 接纳面不得宽于该闸）。 */
+export const IMAGE_MAX_BYTES = 15_000_000
+
+/** 合计上限 30MB ∕ 轮（超阈的**溢出部分**弃、其余照发 —— 与单项阈同单位）。 */
+export const TURN_MAX_BYTES = 30_000_000
+
+/** 栅格四型（捕获组 = `ext` 源 —— dataURL 媒体类型即实际字节的声明；表外类型恒不成附件）。 */
+const DATA_URL_RE = /^data:image\/(png|jpe?g|gif|webp);base64,(.+)$/
+
+/** dataURL ⇒ `{ ext, buffer }` ∥ `null`：栅格四型；表外媒体类型 ∕ 空载荷 ∕ 超单项阈 ⇒ `null`
+ *  （巨图在落盘时刻即弃 —— 不留给 `read_image` 调用时报错）。 */
+export function parseDataUrl(value) {
+  const hit = typeof value === "string" ? value.match(DATA_URL_RE) : null
+  if (!hit) return null
+  const buffer = Buffer.from(hit[2], "base64")
+  if (buffer.length === 0 || buffer.length > IMAGE_MAX_BYTES) return null
+  return { ext: hit[1] === "jpeg" ? "jpg" : hit[1], buffer }
+}
+
+/** 非多模态判据（单源 = 规格表 `multimodal` 位）：显式 `true` 之外一切（未声明 ∕ 未知模型 ∕ 模型缺省）
+ *  ⇒ `true`。降级判决与本档外「档位处置」（端侧各留其处置面）共用本判据。 */
+export function isNonVisionModel(model) {
+  return specForModel(model).multimodal !== true
+}
+
+/**
+ * 落盘管线：dataURL 串列 ⇒ `{ paths, dropped }`（`dropped` = 未落盘者（解析拒 ∕ 超单项阈 ∕ 预算溢出 ∕ 写失败）——零静默判据）。
+ * 逐项：解析（表外 ∕ 空载荷 ∕ 超条阈 ⇒ 弃）⇒ 合计预算（`running + size ≤ TURN_MAX_BYTES` 才收，
+ * 溢出项弃后**继续扫**）⇒ 写 `<cwd>/.thincoder/tmp/paste-<id>-<i>.<ext>`（`index` = 源序；目录
+ * **懒建** —— 零落盘项 ⇒ 零目录）。`fs` = 写面注入缝（`{ mkdirSync(p, {recursive}), writeFileSync(p, buf) }`
+ * —— `node:fs` 同名面；缺 ∕ 形违 ⇒ 抛，fail-loud：写面未接线不得静默扮成「全部弃」）。
+ * 出口零抛（缝缺除外）：无 cwd ∕ 建面 ∕ 写面失败 ⇒ 相应项弃 + 一次诊断（附件面不把回合驱动带崩）。
+ */
+export function savePastedImages(dataUrls, cwd, { fs } = {}) {
+  const list = Array.isArray(dataUrls) ? dataUrls : []
+  if (list.length === 0) return { paths: [], dropped: 0 } // 空表先于缝校验早退（零判据面 —— 缝不检）
+  if (typeof fs?.mkdirSync !== "function" || typeof fs?.writeFileSync !== "function") {
+    throw new TypeError("savePastedImages: fs seam missing — inject { mkdirSync, writeFileSync } (the write face must not silently drop every image)")
+  }
+  if (typeof cwd !== "string" || cwd === "") {
+    console.error(`[attachments] no project cwd — ${list.length} pasted image(s) dropped`)
+    return { paths: [], dropped: list.length }
+  }
+  const tmpDir = join(cwd, ".thincoder", "tmp")
+  const runId = Date.now().toString(36) + Math.random().toString(36).slice(2, 6) // 命名先例 = image-handler.mjs:56
+  const paths = []
+  let dropped = 0
+  let budget = TURN_MAX_BYTES
+  let dir = null // `null` = 未试 · `false` = 建失败（一次诊断后逐项弃）· string = 可用目录
+  const ensureDir = () => {
+    if (dir === null) {
+      try { fs.mkdirSync(tmpDir, { recursive: true }); dir = tmpDir }
+      catch (error) { dir = false; console.error(`[attachments] tmp dir unavailable: ${tmpDir}`, error) }
+    }
+    return dir !== false
+  }
+  for (let i = 0; i < list.length; i += 1) {
+    const parsed = parseDataUrl(list[i])
+    if (parsed === null || parsed.buffer.length > budget) { dropped += 1; continue } // 表外 ∕ 超阈 ⇒ 弃，继续扫
+    if (!ensureDir()) { dropped += 1; continue }
+    const file = join(tmpDir, `paste-${runId}-${i}.${parsed.ext}`)
+    try {
+      fs.writeFileSync(file, parsed.buffer)
+      paths.push(file)
+      budget -= parsed.buffer.length
+    } catch (error) {
+      dropped += 1
+      console.error(`[attachments] image write failed: ${file}`, error)
+    }
+  }
+  return { paths, dropped }
+}
+
+/**
+ * 非多模态降级（判据 + 结果成形；读图 = 注入缝）：判据 = `images` 非空 ∧ `model` 在场 ∧
+ * `isNonVisionModel(model)`。`visionReader({ paths, signal })` ⇒ `{ ok, description }`（缺省实现 = 核
+ * `vision-reader.mjs` `runVisionReader`；注入实现闭包自身上下文）；成功 ⇒ 描述注文（`[图片 <路径表> 描述: <描述>]`，正文空 ⇒ 描述独占）+ `images`
+ * 清空；无返回 ∕ `ok` 非真 ∕ 空描述 ∕ 异常 ⇒ 原样兜底（`{ text, images }` 不动 —— 不静默丢）。
+ * `visionReader` 缺 ∕ 形违 ⇒ 抛（fail-loud：降级路径未接线不得静默扮成「原样兜底」）；判据未过
+ * ⇒ 早退（缝不检、零调用）。返回 `{ text, images, downgraded }`（成功径 `images` = `undefined`）。
+ */
+export async function downgradeNonVisionImages({ text, images, model, visionReader, signal } = {}) {
+  const keep = { text, images, downgraded: false }
+  if (!Array.isArray(images) || images.length === 0) return keep // 无图 ⇒ no-op（VSC :110 同判）
+  if (!model || !isNonVisionModel(model)) return keep // 多模态主模型 ∕ 模型缺省 ⇒ 不降级
+  if (typeof visionReader !== "function") {
+    throw new TypeError("downgradeNonVisionImages: visionReader seam missing — inject the one-shot vision-subagent reader")
+  }
+  let out = null
+  try { out = await visionReader({ paths: images, signal }) } catch { out = null }
+  if (out?.ok !== true || typeof out.description !== "string" || out.description.trim() === "") return keep
+  const marker = `[图片 ${images.join("、")} 描述: ${out.description.trim()}]`
+  return { text: text?.trim() ? `${text}\n\n${marker}` : marker, images: undefined, downgraded: true }
+}