@thincoder/core 0.10.8 → 0.10.9

package/tools/ssh.mjs

@@ -1,10 +1,10 @@
 /**
  * tools/ssh.mjs — SSH 会话工具面（薄接线）：schema ∥ 参数校验 ∥ `isReadonlyAction` ∥ 回执/错误形
- * （设计 = `docs/core/design/TOOLS.md` §6.22 —— D-TO17/D-TO18 · 台账 #1436；机制单点 =
- * `agent-tools/ssh-session.mjs`；描述档 = `tool-docs/ssh.md`）。
+ * （设计 = `docs/core/design/TOOLS.md` §6.22 —— D-TO17/D-TO18 · 台账 #1436；保存面 D-TO19/D-TO20 · 台账 #1602；
+ * 机制单点 = `agent-tools/ssh-session.mjs`（保存件 = `agent-tools/ssh-vault.mjs`）；描述档 = `tool-docs/ssh.md`）。
  *
- * 分类钩子（KD-2 ∥ KD-11 同式——动作级，工具级只读位恒 false）：免审 = `list` ∥ `read`
- * （只读豁免，NS3 判据）；过门 = `connect` ∥ `send` ∥ `secret_input` ∥ `close`——**携密动作仍属
+ * 分类钩子（KD-2 ∥ KD-11 同式——动作级，工具级只读位恒 false）：免审 = `list` ∥ `read` ∥ `credentials`
+ * （只读豁免，NS3 判据）；过门 = `connect` ∥ `send` ∥ `secret_input` ∥ `close` ∥ `forget`——**携密动作仍属
  * 写动作**，门不放松；携密径审批文案 = 掩码占位（`permission.mjs`，值不回显 ⇒ 不入上下文 / 审批记录）。
  *
  * 失败回执**返回**（不 throw）——首行 `Error: …` = 模型面失败形（`bash` / `browser` 既例）；
@@ -14,7 +14,7 @@
  */
 import { DESC } from "./shared.mjs"
 
-export const SSH_ACTIONS = ["connect", "send", "read", "secret_input", "close", "list"]
+export const SSH_ACTIONS = ["connect", "send", "read", "secret_input", "close", "list", "credentials", "forget"]
 
 /** 参数校验（缺必填 / 形错 ⇒ `Error: …`——不执行；§6.22 动作表逐动作必填面）。 */
 export function validateArgs(args) {
@@ -29,7 +29,14 @@ export function validateArgs(args) {
     }
     return null
   }
-  if (action === "list") return null
+  if (action === "list" || action === "credentials") return null
+  if (action === "forget") {
+    if (typeof args.host !== "string" || args.host.trim() === "") return "Error: forget requires host"
+    if (args.port !== undefined && args.port !== null && args.port !== "" && !Number.isFinite(Number(args.port))) {
+      return "Error: forget port must be a number"
+    }
+    return null
+  }
   if (typeof args.id !== "string" || args.id.trim() === "") {
     return `Error: ${action} requires id (the session id from connect, form "ssh#N")`
   }
@@ -43,10 +50,10 @@ export const sshTool = {
   parameters: {
     type: "object",
     properties: {
-      action: { type: "string", enum: SSH_ACTIONS, description: "Action to run (one per call): connect | send | read | secret_input | close | list." },
-      host: { type: "string", description: "connect: target host (IP or name)." },
+      action: { type: "string", enum: SSH_ACTIONS, description: "Action to run (one per call): connect | send | read | secret_input | close | list | credentials | forget." },
+      host: { type: "string", description: "connect / forget: target host (IP or name)." },
       user: { type: "string", description: "connect: login user (optional: your local ssh config decides, else the user recorded for this host locally)." },
-      port: { type: "number", description: "connect: TCP port (optional, default 22)." },
+      port: { type: "number", description: "connect / forget: TCP port (optional, default 22)." },
       label: { type: "string", description: "connect: short human label for this session (optional); secret_input: label for the value being sent." },
       promptPattern: { type: "string", description: "connect: regex that marks the shell prompt as ready (optional): send/read then settle the moment the prompt appears instead of waiting out the silence window." },
       id: { type: "string", description: "send / read / secret_input / close: session id from connect (`ssh#N`)." },
@@ -54,13 +61,14 @@ export const sshTool = {
       settle: { type: "boolean", description: "send: wait for the ready verdict before returning (default true); false returns right after the bytes are written." },
       timeoutMs: { type: "number", description: "send / read: wait budget override (default 10000) — on expiry the call returns partial output with a readable line." },
       maxChars: { type: "number", description: "read: return cap override (default 8000; the full output stays in the session log)." },
+      identityFile: { type: "string", description: "connect: private-key path to offer (`-i`, `~` expands); remembered for this host and reused when omitted (optional)." },
     },
     required: ["action"],
   },
-  // 非工具级只读：动作级分类钩子接管（§6.22 NS3——`list` / `read` 免审）；也因此不进只读角色的子代工具表。
+  // 非工具级只读：动作级分类钩子接管（§6.22 NS3——`list` / `read` / `credentials` 免审）；也因此不进只读角色的子代工具表。
   readonly: false,
   isReadonlyAction(args) {
-    return args?.action === "list" || args?.action === "read"
+    return args?.action === "list" || args?.action === "read" || args?.action === "credentials"
   },
   async execute(args, ctx) {
     const invalid = validateArgs(args)
@@ -74,6 +82,7 @@ export const sshTool = {
       res = await mod.connectSsh(parent, ctx, {
         host: args.host, user: args.user ?? null, port: args.port ?? null,
         label: args.label ?? null, promptPattern: args.promptPattern ?? null,
+        identityFile: args.identityFile ?? null,
       })
     } else if (action === "send") {
       res = await mod.sendSsh(parent, ctx, { id: args.id, data: args.data, settle: args.settle !== false, timeoutMs: args.timeoutMs })
@@ -83,6 +92,10 @@ export const sshTool = {
       res = await mod.secretInputSsh(parent, ctx, { id: args.id, label: args.label ?? null })
     } else if (action === "close") {
       res = await mod.closeSsh(parent, ctx, { id: args.id })
+    } else if (action === "credentials") {
+      res = mod.credentialsSsh()
+    } else if (action === "forget") {
+      res = mod.forgetSsh({ host: args.host, port: args.port ?? null })
     } else {
       res = mod.listSsh(parent)
     }

package/tools/web-deepseek.mjs

@@ -0,0 +1,172 @@
+/**
+ * web-deepseek.mjs — DeepSeek Search / Fetch backend for the `websearch` & `fetch` tools
+ * (design = `docs/core/design/TOOLS.md` §6.23 · ledger #1605).
+ *
+ * Key source = the first `providers[]` entry whose baseURL host is the official
+ * `api.deepseek.com` and whose apiKey resolves non-empty (`${env:VAR}` resolved at use
+ * time — an unresolved reference makes that entry ineligible, never throws). Zero new
+ * config: a configured DeepSeek provider is enough.
+ *
+ * The tools never fail because of this backend: every export returns a pure value
+ * (`{ status: "ok" | "empty" | "failed" | "unavailable" }`) and never throws.
+ * 401/402/403/404 trip a per-agent breaker (WeakSet); 408/429/5xx retry once (500 ms);
+ * everything else falls back to the caller's existing chain.
+ */
+import { URL } from "node:url"
+import { truncate, isPrivateHost } from "./shared.mjs"
+import { resolveProviderSecrets } from "../env-ref.mjs"
+import { proxyFetch } from "../proxy.mjs"
+import { logEvent } from "../log.mjs"
+
+// D-WB2: endpoints are fixed constants — `baseURL` only decides eligibility (a user's
+// `/v1` suffix or prefix must not build a doubled path, and the key only goes to the
+// official host).
+const SEARCH_URL = "https://api.deepseek.com/v1/tools/search"
+const FETCH_URL = "https://api.deepseek.com/v1/tools/fetch"
+const DEEPSEEK_HOST = "api.deepseek.com"
+const TIMEOUT_MS = 15_000
+const RETRY_DELAY_MS = 500 // D-WB5: fixed single backoff (no Retry-After parsing)
+const COST_PER_CALL = 0.00075 // $0.75 / 1000 successful requests — `count` does not change the price
+const TRIP_STATUS = new Set([401, 402, 403, 404])
+const RETRY_STATUS = (() => {
+  const codes = new Set([408, 429])
+  for (let code = 500; code <= 599; code++) codes.add(code)
+  return codes
+})()
+
+let _transport = proxyFetch
+let _breaker = new WeakSet()
+
+/** Test seam (CONFIG.md §6.2 ③ — paired): swap the transport; reset also clears the breaker. */
+export function _setDeepseekTransportForTest(fn) { _transport = typeof fn === "function" ? fn : proxyFetch }
+export function _resetDeepseekTransportForTest() { _transport = proxyFetch; _breaker = new WeakSet() }
+
+/** `local` skips the DeepSeek backend; anything else (missing ∥ misspelled ∥ non-string) = `auto` (fail-open). */
+export function backendMode(cfg, key) {
+  return cfg?.[key]?.backend === "local" ? "local" : "auto"
+}
+
+/** First qualifying channel in stored order → `{ apiKey }` | null. Never throws. */
+function deepseekChannel(cfg) {
+  const list = Array.isArray(cfg?.providersList) ? cfg.providersList
+    : Array.isArray(cfg?.providers) ? cfg.providers : []
+  for (const entry of list) {
+    if (entry === null || typeof entry !== "object") continue
+    let url
+    try { url = new URL(String(entry.baseURL ?? "")) } catch { continue }
+    if (url.protocol !== "https:") continue
+    const host = url.hostname.toLowerCase().replace(/\.$/, "") // trailing-dot host still official
+    if (host !== DEEPSEEK_HOST) continue // subdomains never qualify (x.api.deepseek.com)
+    if (url.port !== "" && url.port !== "443") continue // non-standard port could impersonate
+    let apiKey
+    try { apiKey = resolveProviderSecrets(entry).apiKey } catch { continue } // unset env ref ⇒ ineligible
+    if (typeof apiKey !== "string" || apiKey.trim() === "") continue
+    return { apiKey: apiKey.trim() }
+  }
+  return null
+}
+
+const tripped = (agent) => agent !== null && typeof agent === "object" && _breaker.has(agent)
+
+/** Break the backend for this agent identity (single domain — search ∥ fetch share it, D-WB3). */
+function trip(agent) {
+  if (agent !== null && typeof agent === "object") _breaker.add(agent)
+}
+
+/** One POST. Returns `{ kind: "ok", data }` | `{ kind: "http", status }` | `{ kind: "net", timeout }` | `{ kind: "json" }`. */
+async function postOnce(url, body, apiKey, proxyUri) {
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS)
+  try {
+    const res = await _transport(url, {
+      method: "POST",
+      // Same header shape as the Tavily leg (`web.mjs` bearer precedent).
+      headers: { "Content-Type": "application/json", "Authorization": `Bearer ${apiKey}` },
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+    }, proxyUri)
+    if (!res || res.ok !== true) {
+      try { await res?.body?.cancel?.() } catch { /* body already closed */ }
+      return { kind: "http", status: Number(res?.status ?? 0) }
+    }
+    try { return { kind: "ok", data: await res.json() } } catch { return { kind: "json" } }
+  } catch (e) {
+    return { kind: "net", timeout: e?.name === "AbortError" }
+  } finally { clearTimeout(timer) }
+}
+
+/** One logical call: retry once (408/429/5xx), trip on 401/402/403/404, otherwise fall back. */
+async function request(url, body, apiKey, proxyUri, tool, agent) {
+  const started = Date.now()
+  let r = await postOnce(url, body, apiKey, proxyUri)
+  if (r.kind === "http" && RETRY_STATUS.has(r.status)) {
+    await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS))
+    r = await postOnce(url, body, apiKey, proxyUri)
+  }
+  if (r.kind === "ok") return { ok: true, data: r.data }
+  if (r.kind === "http" && TRIP_STATUS.has(r.status) && agent !== null && typeof agent === "object") {
+    trip(agent)
+    // Tripping line only (transient fallbacks stay quiet — ⑤).
+    logEvent("web:deepseek", { tool, status: r.status, tripped: true, ms: Date.now() - started })
+  }
+  const reason = r.kind === "http" ? `http ${r.status}`
+    : r.kind === "net" ? (r.timeout ? "timeout" : "network")
+      : "malformed json"
+  return { ok: false, reason }
+}
+
+/** Response → tool text: `[deepseek]` block per result, same numbered shape as the Tavily ∥ Bing legs. */
+function renderSearch(data, limit) {
+  const list = Array.isArray(data?.results) ? data.results : []
+  const results = list.slice(0, limit)
+  if (results.length === 0) return { n: 0, text: "" }
+  const blocks = results.map((r, i) => {
+    const meta = []
+    if (typeof r?.date === "string" && r.date.trim() !== "") meta.push(r.date)
+    if (Number.isFinite(r?.authority) && r.authority >= 0) meta.push(`authority ${r.authority}`) // -1 = unknown ⇒ omitted
+    if (Number.isFinite(r?.rerank_score)) meta.push(`rerank ${r.rerank_score}`)
+    const summary = typeof r?.summary === "string" && r.summary.trim() !== ""
+      ? r.summary
+      : (typeof r?.snippet === "string" ? r.snippet : "")
+    const lines = [`${i + 1}. [deepseek] ${r?.title ?? ""}`, `   ${r?.url ?? ""}`]
+    if (meta.length > 0) lines.push(`   ${meta.join(" · ")}`)
+    if (summary !== "") lines.push(`   ${summary}`)
+    return lines.join("\n")
+  })
+  return { n: results.length, text: truncate(blocks.join("\n\n")) }
+}
+
+/** search — `count` = the tool-face limit (`web.mjs` already clamps it to 20); `< 1` ⇒ 1. Never throws. */
+export async function deepseekSearch({ cfg, query, limit = 8, proxy = null, agent = null } = {}) {
+  const channel = deepseekChannel(cfg)
+  if (channel === null) return { status: "unavailable" }
+  if (tripped(agent)) return { status: "failed", reason: "breaker open" }
+  const count = Math.min(50, Math.max(1, Number.isFinite(limit) ? Math.floor(limit) : 8))
+  const started = Date.now()
+  const r = await request(SEARCH_URL, { query, count, need_content: false }, channel.apiKey, proxy, "search", agent)
+  if (!r.ok) return { status: "failed", reason: r.reason }
+  const { n, text } = renderSearch(r.data, count)
+  logEvent("web:deepseek", { tool: "search", n, ms: Date.now() - started, cost: n > 0 ? COST_PER_CALL : 0 })
+  return n > 0 ? { status: "ok", text, n } : { status: "empty" }
+}
+
+/** fetch — title + Markdown; empty `content` ⇒ `empty` (caller falls back to the local fetch). Never throws. */
+export async function deepseekFetch({ cfg, url, proxy = null, agent = null } = {}) {
+  const channel = deepseekChannel(cfg)
+  if (channel === null) return { status: "unavailable" }
+  if (tripped(agent)) return { status: "failed", reason: "breaker open" }
+  // `web.mjs` runs the SSRF gate before calling; keep a second one here so a direct
+  // caller can never send a private/metadata URL to a third party either.
+  let target
+  try { target = new URL(url) } catch { return { status: "failed", reason: "invalid url" } }
+  if (isPrivateHost(target.hostname)) return { status: "failed", reason: "private url" }
+  const started = Date.now()
+  const r = await request(FETCH_URL, { url }, channel.apiKey, proxy, "fetch", agent)
+  if (!r.ok) return { status: "failed", reason: r.reason }
+  const title = typeof r.data?.title === "string" ? r.data.title : ""
+  const content = typeof r.data?.content === "string" ? r.data.content : ""
+  const n = content.trim() === "" ? 0 : content.length
+  logEvent("web:deepseek", { tool: "fetch", n, ms: Date.now() - started, cost: n > 0 ? COST_PER_CALL : 0 })
+  if (n === 0) return { status: "empty" }
+  return { status: "ok", text: truncate(`[deepseek] ${title}\n\n${content}`), n }
+}

package/tools/web.mjs

@@ -2,11 +2,17 @@ import { DESC, truncate, stripTags, htmlToText, isPrivateHost } from "./shared.m
 import { URL } from "node:url";
 import { proxyFetch } from "../proxy.mjs";
 import { resolveEnvRefs } from "../env-ref.mjs";
+import { backendMode, deepseekSearch, deepseekFetch } from "./web-deepseek.mjs";
 
 export const UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
 const FETCH_TIMEOUT = 15_000
 // D-TF3：网络失败错误文本追加 proxy 提示——纯文本提示，不自动路由（2026-08-31 裁定：proxy 显式传不自动应用）
 const PROXY_HINT = "network failure — retry with proxy: 'http://host:port' if the target is blocked"
+// WEB-BACKEND-DEEPSEEK（TOOLS.md §6.23 ④）：DeepSeek 未出结果 ⇒ 回落腿承接后结果末尾恰一行（按返回态分叉）。
+// fetch 腿两态零提示（D-WB6）；`unavailable` ∥ `local` 零提示（零回归）。
+const deepseekNote = (status, leg) => status === "empty"
+  ? `(deepseek returned no results — results from ${leg})`
+  : `(deepseek backend unavailable — results from ${leg})`
 
 // ── Web search (Bing; direct by default, through proxy when configured and web toggle on) ──
 
@@ -107,18 +113,29 @@ export const websearchTool = {
     // 2026-08-31 ruling: proxy is a PER-CALL decision (args.proxy), never the config.json
     // fixed configuration. Model picks by target: github/foreign → pass proxy; gitee/domestic → omit.
     const proxyUri = args.proxy ?? null
+    // DeepSeek first when a qualifying provider is configured (TOOLS.md §6.23 ②) — `local`,
+    // no channel, or a query over 128 chars ⇒ zero calls, and the chain below runs verbatim.
+    let dsNote = null
+    if (backendMode(ctx?.agent?.config, "websearch") !== "local"
+      && typeof args.query === "string" && args.query.length <= 128) {
+      const ds = await deepseekSearch({ cfg: ctx?.agent?.config, query: args.query, limit, proxy: proxyUri, agent: ctx?.agent })
+      if (ds.status === "ok") return ds.text
+      if (ds.status === "empty" || ds.status === "failed") dsNote = ds.status
+    }
+    // A DeepSeek outcome only adds a line once a fallback leg actually carries results.
+    const withNote = (text, leg) => (dsNote ? `${text}\n\n${deepseekNote(dsNote, leg)}` : text)
     // Structured search first when a Tavily key is configured — stable, dated,
     // no HTML scraping. Falls back to Bing silently.
     const tavily = await fetchTavily(args.query, limit, ctx, proxyUri)
     if (tavily && tavily.results.length > 0) {
-      return truncate(tavily.results.slice(0, limit).map((r, i) => `${i + 1}. [tavily] ${r.title}\n   ${r.href}\n   ${r.snippet}`).join("\n\n"))
+      return withNote(truncate(tavily.results.slice(0, limit).map((r, i) => `${i + 1}. [tavily] ${r.title}\n   ${r.href}\n   ${r.snippet}`).join("\n\n")), "tavily")
     }
     if (args.engine) {
       const engine = ENGINES.find(e => e.name === args.engine)
       if (!engine) return `Unknown engine '${args.engine}'. Available: ${ENGINE_NAMES.join(", ")}`
       const fetched = await fetchEngine(engine, args.query, page, proxyUri)
       if (!fetched || fetched.results.length === 0) return "(no results)"
-      return truncate(fetched.results.slice(0, limit).map((r, i) => `${i + 1}. [${engine.label}] ${r.title}\n   ${r.href}\n   ${r.snippet}`).join("\n\n"))
+      return withNote(truncate(fetched.results.slice(0, limit).map((r, i) => `${i + 1}. [${engine.label}] ${r.title}\n   ${r.href}\n   ${r.snippet}`).join("\n\n")), engine.name)
     }
     const promises = ENGINES.map(e => fetchEngine(e, args.query, 1, proxyUri))
     const fetched = (await Promise.all(promises)).filter(Boolean)
@@ -135,7 +152,9 @@ export const websearchTool = {
         }
       }
     }
-    return truncate(merged.slice(0, limit).map((r, i) => `${i + 1}. [${r._engine}] ${r.title}\n   ${r.href}\n   ${r.snippet}`).join("\n\n"))
+    // Note only when a leg actually carried results — an empty merge keeps today's output.
+    const mergedText = truncate(merged.slice(0, limit).map((r, i) => `${i + 1}. [${r._engine}] ${r.title}\n   ${r.href}\n   ${r.snippet}`).join("\n\n"))
+    return merged.length > 0 ? withNote(mergedText, fetched[0].engine) : mergedText
   },
 }
 
@@ -193,9 +212,15 @@ export const fetchTool = {
     required: ["url"],
   },
   readonly: true,
-  async execute(args, _ctx) {
+  async execute(args, ctx) {
     if (!/^https?:\/\//.test(args.url)) throw new Error("url must start with http:// or https://")
     if (isPrivateUrl(args.url)) throw new Error("fetch blocked: internal/private/metadata addresses are not allowed")
+    // DeepSeek returns Markdown (W3); `empty` ∥ `failed` fall through to the local fetch,
+    // both without a result note (D-WB6 — the content face stays verbatim).
+    if (backendMode(ctx?.agent?.config, "fetch") !== "local") {
+      const ds = await deepseekFetch({ cfg: ctx?.agent?.config, url: args.url, proxy: args.proxy ?? null, agent: ctx?.agent })
+      if (ds.status === "ok") return ds.text
+    }
     try {
       // 2026-08-31 ruling: per-call decision — args.proxy when passed, direct otherwise.
       const proxyUri = args.proxy ?? null