@thincoder/core 0.10.7 → 0.10.8

package/tools/ssh.mjs

@@ -0,0 +1,92 @@
+/**
+ * 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`）。
+ *
+ * 分类钩子（KD-2 ∥ KD-11 同式——动作级，工具级只读位恒 false）：免审 = `list` ∥ `read`
+ * （只读豁免，NS3 判据）；过门 = `connect` ∥ `send` ∥ `secret_input` ∥ `close`——**携密动作仍属
+ * 写动作**，门不放松；携密径审批文案 = 掩码占位（`permission.mjs`，值不回显 ⇒ 不入上下文 / 审批记录）。
+ *
+ * 失败回执**返回**（不 throw）——首行 `Error: …` = 模型面失败形（`bash` / `browser` 既例）；
+ * 无 UI 考（缺 `ctx.onSecretInput` 回调）⇒ 机制档抛可读错（`question.mjs` 无 UI 抛例同旨）。
+ * 会话跨调用存活于池（非本档持有）；depth>0 排除（`agent/helpers.mjs` `SUBAGENT_TOOL_EXCLUSIONS`）。
+ * 动态 import（W8 契约②：agent-tools 静态链达 node:sqlite——端壳静态闭包须保持零命中）。
+ */
+import { DESC } from "./shared.mjs"
+
+export const SSH_ACTIONS = ["connect", "send", "read", "secret_input", "close", "list"]
+
+/** 参数校验（缺必填 / 形错 ⇒ `Error: …`——不执行；§6.22 动作表逐动作必填面）。 */
+export function validateArgs(args) {
+  const action = args?.action
+  if (!SSH_ACTIONS.includes(action)) {
+    return `Error: unknown ssh action "${action ?? ""}" — actions: ${SSH_ACTIONS.join(", ")}`
+  }
+  if (action === "connect") {
+    if (typeof args.host !== "string" || args.host.trim() === "") return "Error: connect requires host"
+    if (args.port !== undefined && args.port !== null && args.port !== "" && !Number.isFinite(Number(args.port))) {
+      return "Error: connect port must be a number"
+    }
+    return null
+  }
+  if (action === "list") return null
+  if (typeof args.id !== "string" || args.id.trim() === "") {
+    return `Error: ${action} requires id (the session id from connect, form "ssh#N")`
+  }
+  if (action === "send" && typeof args.data !== "string") return "Error: send requires data"
+  return null
+}
+
+export const sshTool = {
+  name: "ssh",
+  description: DESC("ssh"),
+  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)." },
+      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)." },
+      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`)." },
+      data: { type: "string", description: "send: text to type into the session (a trailing newline is passed as-is; otherwise Enter is sent as `\\r`)." },
+      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)." },
+    },
+    required: ["action"],
+  },
+  // 非工具级只读：动作级分类钩子接管（§6.22 NS3——`list` / `read` 免审）；也因此不进只读角色的子代工具表。
+  readonly: false,
+  isReadonlyAction(args) {
+    return args?.action === "list" || args?.action === "read"
+  },
+  async execute(args, ctx) {
+    const invalid = validateArgs(args)
+    if (invalid) return invalid
+    // 动态 import（W8 契约②——与 bash / browser 异步面同式）。
+    const mod = await import("../agent-tools/ssh-session.mjs")
+    const parent = ctx?.agent ?? null
+    const action = args.action
+    let res
+    if (action === "connect") {
+      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,
+      })
+    } else if (action === "send") {
+      res = await mod.sendSsh(parent, ctx, { id: args.id, data: args.data, settle: args.settle !== false, timeoutMs: args.timeoutMs })
+    } else if (action === "read") {
+      res = await mod.readSsh(parent, ctx, { id: args.id, timeoutMs: args.timeoutMs, maxChars: args.maxChars })
+    } else if (action === "secret_input") {
+      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 {
+      res = mod.listSsh(parent)
+    }
+    if (res?.error) return res.error.startsWith("Error:") ? res.error : `Error: ${res.error}`
+    return res?.text ?? "(no output)"
+  },
+}

package/vision-reader.mjs

@@ -1,8 +1,8 @@
 /**
  * vision-reader.mjs — 非多模态降级读图跑者（上提核件 —— parity-b4 W0 · 2026-09-29）。
  *
- * 上提源 = VSC `thincoder-vscode/src/extension/vision-channel.mjs:14`（`findVisionChannel` 逐字）
- * + `image-handler.mjs:70-95`（`runVisionReader` 逐字）；VSC 自持跑者 ∕ 渠道副本已随迁移轮（parity-b4）删。
+ * 上提源 = VSC `thincoder-vscode/src/extension/vision-channel.mjs`（#1127 已删档；`findVisionChannel` 逐字）
+ * + `image-handler.mjs`（`runVisionReader` 逐字）；VSC 自持跑者 ∕ 渠道副本已随迁移轮（parity-b4）删。
  * 消费面 = VSC `image-handler.mjs`（已改指本档）· 桌面 `src/main/attachments.mjs`
  * （降级适配器缺省 = 本档 —— `visionReader` 缝的核默认实现）。
  *
@@ -19,13 +19,13 @@
  *
  *  W8 契约②（2026-09-29 断链）：`agent.mjs` ∕ `agent-tools/subagent-async.mjs` 静态链达 `node:sqlite`
  *  （`agent.mjs` → `agent/setup.mjs` → `memory.mjs` → `memory/schema.mjs`）⇒ 两端一律**函数体内动态 import**
- *  （约定源 = `ledger.mjs:16`；实例 = `tools/index.mjs:63`）；本档静态边只留闭包净件（`config-io.mjs` ∕
+ *  （约定源 = `ledger.mjs`；实例 = `tools/index.mjs` 的 `assembleBuiltinTools`）；本档静态边只留闭包净件（`config-io.mjs` ∕
  *  `tools/index.mjs`）。
  */
 import { resolveProviders } from "./config-io.mjs"
 import { assembleBuiltinTools } from "./tools/index.mjs"
 
-/** 读图墙钟上限（VSC `image-handler.mjs:70` 同值——一次性子代理的成功径上限）。 */
+/** 读图墙钟上限（VSC `image-handler.mjs` 的 `runVisionReader` 同值——一次性子代理的成功径上限）。 */
 export const VISION_READ_TIMEOUT_MS = 60_000
 
 /** 找可跑视觉读图的渠道：`{ provider, model }` ∥ `null`。