dsh-pwsh-plugin 0.0.0-stage → 0.2.13

package/plugin/index.mjs

@@ -0,0 +1,580 @@
+/**
+ * pwsh-run —— 常驻 PowerShell 会话工具（插件行）
+ *
+ * 为什么需要它
+ *   DSH 的 bash 工具把命令包成 /bin/bash -c "<cmd>" 再交给 shell，
+ *   所以任何经过 bash 的 PowerShell 命令，$变量 会先被外层双引号展开、
+ *   heredoc 也会在那一层失效（实测：pwsh -Command "Write-Output \"var=$abc\"" 输出 var=）。
+ *   原生 pwsh 工具本身不吃 $，但受 Windows 命令行长度限制（实测 32700 字符即 ENAMETOOLONG），
+ *   且每次都是全新进程，变量 / 当前目录 / 已导入模块不跨调用保留。
+ *
+ * 本工具把脚本正文直接经 stdin 喂给一个常驻 pwsh 进程：
+ *   - 零转义：不经过任何 shell，$ / 引号 / here-string / 中文原样送达
+ *   - 无长度限制：20 万字符的单次脚本实测跑通（原生工具在同一长度上必撞命令行上限）
+ *   - 省启动：原生 pwsh 每次冷启动实测约 730ms，这边热态往返约 8ms
+ *   - 状态保留：变量、当前目录、$env:、已导入模块跨调用保留
+ *
+ * 与原生 pwsh 工具的关系：并存，不替换。原生工具继续负责需要逐次沙箱、
+ * 审批、后台 job 晋升的场景；本工具负责长脚本与需要状态的场景。
+ *
+ * 沙箱：常驻进程在**启动时**整体包进 ctx.sandbox.confine 返回的受限 argv，
+ *   之后它的每一次读/写都受同一个 workspace 边界约束（ACL 受限令牌是进程级，
+ *   不是逐命令级——这一点与原生工具等价，实测 workspace 外写入全部被拒）。
+ *   read-only 模式下 pwsh 以 ConstrainedLanguage 运行，无法构造 runspace，
+ *   因此常驻会话在该模式下不启动，直接报错让模型改用原生 pwsh 工具。
+ *   ctx.sandboxPolicy 缺席时同样拒绝启动（fail-closed），除非显式 config.allowUnconfined: true。
+ *
+ * 已知边界（已写进工具描述，模型可见）
+ *   - 脚本内 exit N 只结束当次调用，退出码不可观测（runspace 语义限制）。
+ *   - 超时 / 取消会终止整个会话进程（连带回收子进程树）并自动重建，状态丢失。
+ */
+
+import { readFileSync } from 'node:fs'
+import { DEFAULT_MAX_OUTPUT_BYTES, bootArgv, startSession } from './session.mjs'
+import { installReleaseLive, startAutoUpdate } from './auto-update.mjs'
+import { preflightInstall } from './update-apply.mjs'
+import { UpdateChecker } from './update-check.mjs'
+
+/** 加载器诊断里显示的插件名。 */
+export const name = 'pwsh-run'
+
+/** 注册前必须已有的服务。 */
+export const inject = ['subprocess', 'tools']
+
+const DEFAULT_TIMEOUT_MS = 120000
+const DEFAULT_IDLE_MS = 30 * 60 * 1000
+const DEFAULT_MAX_SESSIONS = 4
+/** 调用方超时之外多给的余量：服务端被打断后还要把尾部输出吐完、写结束标记。 */
+const RESPONSE_GRACE_MS = 5000
+
+/** 服务端脚本：随插件分发，启动时经 -EncodedCommand 送入，不落地临时文件。 */
+const SERVER_SOURCE = readFileSync(new URL('./session-server.ps1', import.meta.url), 'utf8')
+
+const parameters = {
+  type: 'object',
+  properties: {
+    script: {
+      type: 'string',
+      description: 'The PowerShell script body to run. Sent verbatim to a persistent pwsh session — do not escape $, do not wrap it in pwsh -c.',
+    },
+    workdir: {
+      type: 'string',
+      description: 'Optional Windows working directory to Set-Location into before running (e.g. D:\\proj). It persists for later calls in the same session; an invalid path fails the call before the script runs.',
+    },
+    timeoutMs: {
+      type: 'number',
+      description: 'Timeout for this call in milliseconds; defaults to 120000. On timeout the session process is terminated and rebuilt.',
+    },
+  },
+  required: ['script'],
+  additionalProperties: false,
+}
+
+/**
+ * 解析子进程的启动目录。
+ * 与 presets/shared/custom-bash.mjs 同款：workingDirectory 服务优先（会话中途切目录后
+ * header.cwd 不会更新），服务缺失时退回 header.cwd，再退回进程 cwd。
+ */
+async function resolveCwd(ctx, agent, signal) {
+  try {
+    const service = ctx.get('workingDirectory')
+    if (service !== undefined && agent !== undefined) return await service.ensure(agent, signal)
+  } catch {
+    // 服务异常时退回旧路径，不让一次目录查询拖垮工具调用。
+  }
+  const header = agent?.session?.header
+  if (typeof header?.cwd === 'string' && header.cwd.length > 0) return header.cwd
+  return process.cwd()
+}
+
+/**
+ * 把一个字符串安全地拼进 PowerShell 源码。
+ * 必须用单引号字面量：JSON 的双引号写法会被 PowerShell 当成可展开字符串，
+ * 路径里一旦出现 $ 或反引号（如 D:\$Recycle.Bin）就会被解析掉，
+ * 而且 JSON 会把反斜杠加倍成 \\，与 PowerShell 的转义规则并不一致。
+ * PowerShell 单引号里唯一需要转义的字符是单引号本身（写成两个）。
+ */
+function psLiteral(value) {
+  return "'" + String(value).replaceAll("'", "''") + "'"
+}
+
+/**
+ * confine 失败时把原始 Win32 错误翻译成能照着做的说明。
+ * 最常见的一种：工作区根的 DACL 没给 WRITE_DAC / WRITE_OWNER。沙箱要在目录上写 DACL 与
+ * SACL（低完整性标签），缺任一条就会以 Win32 5（拒绝访问）失败，而原始错误只有一句
+ * SetNamedSecurityInfoW failed，看不出该改哪个目录、该给什么权限。
+ */
+function describeConfineFailure(error, workspaceRoot) {
+  const raw = String(error?.message ?? error)
+  if (!/SetNamedSecurityInfoW/.test(raw)) return 'pwsh_run could not confine the session: ' + raw
+  const root = typeof workspaceRoot === 'string' ? workspaceRoot : '(unknown)'
+  return 'pwsh_run could not confine the session: ' + raw
+    + '. The sandbox writes a DACL and an integrity label on the workspace root, which needs its DACL to'
+    + ' grant the current user WRITE_DAC and WRITE_OWNER (full control satisfies both; Modify alone does not).'
+    + ' Workspace root was ' + root + ' — grant yourself full control (icacls "' + root + '" /grant "%USERNAME%":(OI)(CI)F)'
+    + ' or start the session from a directory under your user profile.'
+}
+
+/**
+ * 捕获「子进程起不来」的报错，附上能照着做的说明。
+ *
+ * DSH 的 Windows 沙箱（workspace-write）给进程挂的是 Low 完整性 + WRITE_RESTRICTED 令牌，
+ * 这种令牌建不了匿名管道，于是所有「捕获子进程 stdio」的起法一律失败——`& exe` 也在其中
+ * （PowerShell 的调用运算符内部要建管道）。原始报错只有一句「拒绝访问」，
+ * 看不出这是沙箱边界而不是命令写错了，模型很容易在这里反复换姿势盲试。
+ */
+export function describeExecDenial(text) {
+  // 第一道门必须同时认内层文案：服务端交付的是剥到最内层的异常，`& exe` 到这里的原文是
+  // "StandardOutputEncoding is only supported when standard output is redirected."，没有
+  // "failed to run" 前缀。只按外层文案判定会让这条提示在真实路径上永不出现。
+  if (!/failed to run|StandardOutputEncoding is only supported/.test(text)) return null
+  if (!/拒绝访问|Access is denied|StandardOutputEncoding is only supported/.test(text)) return null
+  return '[The sandbox is blocking that child process: this session runs under a restricted token (Low integrity +'
+    + ' WRITE_RESTRICTED) that cannot create anonymous pipes, so any launch that captures a child\'s stdio fails —'
+    + ' including `& exe`. Launches that do work: (1) [Diagnostics.Process]::Start on'
+    + ' `cmd.exe /c "<exe> <args> > out.txt 2> err.txt"` with UseShellExecute=$false — .ExitCode is correct and'
+    + ' both files carry the output; (2) Start-Process -NoNewWindow -PassThru -Wait -RedirectStandardOutput <file>'
+    + ' -RedirectStandardError <file> — output is captured, but .ExitCode comes back empty. Two things NOT to do:'
+    + ' do not pass CreateNoWindow=$true, and do not call Start-Process without -NoNewWindow — a fresh console'
+    + ' cannot initialize under the restricted token, so the child dies with STATUS_DLL_INIT_FAILED (0xC0000142)'
+    + ' and Windows raises a modal error dialog. Also do not let a child inherit this session\'s stdout: this tool'
+    + ' detaches the child std handles, so session corruption is prevented — the lost output is not.]'
+}
+
+/** 合并调用方取消信号与本地超时信号。 */
+function withTimeout(signal, timeoutMs) {
+  const timeout = AbortSignal.timeout(timeoutMs)
+  return signal === undefined ? timeout : AbortSignal.any([signal, timeout])
+}
+
+export function apply(ctx, config) {
+  const pwshPath = typeof config?.pwshPath === 'string' && config.pwshPath.length > 0 ? config.pwshPath : 'pwsh'
+  const defaultTimeoutMs = Number.isSafeInteger(config?.timeoutMs) && config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS
+  const idleMs = Number.isSafeInteger(config?.idleMs) && config.idleMs > 0 ? config.idleMs : DEFAULT_IDLE_MS
+  const maxSessions = Number.isSafeInteger(config?.maxSessions) && config.maxSessions > 0 ? config.maxSessions : DEFAULT_MAX_SESSIONS
+  const maxOutputBytes = Number.isSafeInteger(config?.maxOutputBytes) && config.maxOutputBytes > 0 ? config.maxOutputBytes : DEFAULT_MAX_OUTPUT_BYTES
+  // 明确放弃边界的唯一开关：策略服务缺席时默认拒绝启动，只有这里能改主意。
+  const allowUnconfined = config?.allowUnconfined === true
+  // 更新检查：查到新版本时在当次调用的输出末尾挂一行。
+  const updateCheck = config?.updateCheck !== false
+  // 自动更新：查到新版本就自己装上，装上即生效（HMR 在场时无需重启）。默认开——
+  // 用户装这个插件图的是「命令不再被转义」，不该再手动盯版本。
+  const autoUpdate = config?.autoUpdate !== false
+
+  // 沙箱服务每次启动会话时再取：插件 apply 可能早于沙箱服务挂载，
+  // 而沙箱缺席时插件仍需能加载（启动会话时给出明确错误即可）。
+  // 入参是 Agent（不是 ToolExecution）：sandboxPolicy.resolve 需要 session 才能读到
+  // 会话的 sandbox/mode 覆盖与 header.cwd。传错形状会静默退回部署默认值
+  // （mode=workspace-write + 配置的 workspaceRoot），边界就跑到 profile 目录去了。
+  const resolvePolicy = (agent) => {
+    const sandboxPolicy = ctx.get('sandboxPolicy')
+    if (sandboxPolicy === undefined) return null
+    const session = agent?.session
+    return sandboxPolicy.resolve(session === undefined ? {} : { session })
+  }
+
+  /**
+   * 安装闸门：自动更新与手动安装共用。
+   *
+   * 热替换会执行本插件的 effect 清理函数，那里 dispose 掉全部常驻会话——正在跑的脚本
+   * 会连人带马被掐断，与直接断电无异。所以安装前先确认没有调用在跑；置位与检查必须在
+   * 同一个同步块里完成，否则中间会挤进一条新调用。
+   */
+  let activeRuns = 0
+  let installing = false
+
+  /** sessionId -> Promise<PwshSession>。用 Promise 占位，避免并发首调用各起一个进程。 */
+  const sessions = new Map()
+
+  const sessionKey = (exec) => {
+    const id = exec?.agent?.session?.id
+    return typeof id === 'string' && id.length > 0 ? id : 'default'
+  }
+
+  const evict = async (key, session) => {
+    sessions.delete(key)
+    if (session !== undefined && session !== null) await session.dispose()
+  }
+
+  /**
+   * 申请安装权：只有「没有调用在跑、也没有别人在装」时才拿得到。
+   *
+   * 检查与置位放在同一个同步块里，中间不会挤进新调用——否则就会出现
+   * 「刚判断空闲、一条调用起来、安装把它的会话掐掉」这种时序空档。
+   */
+  const beginInstall = () => {
+    if (installing || activeRuns > 0) return false
+    installing = true
+    return true
+  }
+  const endInstall = () => { installing = false }
+  /** 交给自动更新循环：忙就别装，推迟整轮。 */
+  const installGate = { tryAcquire: beginInstall, release: endInstall }
+
+  /**
+   * 安装进行中到达的调用先等着：此刻建出来的会话会在热替换那一刻被 dispose，
+   * 等于刚起就断。等到安装收尾再继续——之后的会话属于安装后的世界。
+   */
+  const waitForInstall = async () => {
+    const deadline = Date.now() + 120000
+    while (installing) {
+      if (Date.now() > deadline) throw new Error('pwsh_run: an update is being installed and has not finished; retry in a moment')
+      await new Promise((resolve) => setTimeout(resolve, 100))
+    }
+  }
+
+  /** 取一个活着的会话，必要时新建；超出上限淘汰最久未用的。 */
+  const acquire = async (key, workdir, agent, signal) => {
+    const existing = sessions.get(key)
+    if (existing !== undefined) {
+      let session = null
+      try {
+        session = await existing
+      } catch {
+        sessions.delete(key)
+      }
+      if (session !== null && !session.dead) {
+        session.lastUsed = Date.now()
+        return session
+      }
+      if (session !== null) await session.dispose()
+      sessions.delete(key)
+    }
+
+    const cwd = workdir ?? await resolveCwd(ctx, agent, signal)
+    const pending = (async () => {
+      const executable = await ctx.subprocess.resolveExecutable(pwshPath, undefined, signal)
+      // 常驻进程只在启动时能 confine 一次——但 ACL 受限令牌是**进程级**的，
+      // 之后该进程所有读写都受同一 workspace 边界约束，与原生 pwsh 工具等价（实测）。
+      const policy = resolvePolicy(agent)
+      const boot = bootArgv(SERVER_SOURCE)
+      const plain = [executable].concat(boot)
+      // fail-closed：解析不出边界就拒绝启动，而不是悄悄跑一个不受约束的会话。
+      if (policy === null && allowUnconfined !== true) {
+        throw new Error('pwsh_run: ctx.sandboxPolicy is absent, so the workspace boundary cannot be resolved. ' +
+          'Mount @deepseek-ai/dsh-sandbox-policy, or set config.allowUnconfined: true to accept an unconfined session ' +
+          '(file writes would then NOT be restricted to the workspace).')
+      }
+      if (policy === null || policy.mode === 'danger-full-access') {
+        return await startSession(ctx.subprocess, { executable, cwd, serverSource: SERVER_SOURCE, label: key, maxOutputBytes })
+      }
+      // read-only 下 pwsh 是 ConstrainedLanguage，连 runspace 都建不起来（实测
+      // [Text.UTF8Encoding]::new 即报 "Cannot create type"），常驻会话没法启动。
+      if (policy.mode === 'read-only') {
+        throw new Error('pwsh_run does not support read-only mode: a persistent pwsh session needs FullLanguage ' +
+          '(a read-only sandbox runs pwsh in ConstrainedLanguage, where creating a runspace fails). Use the native pwsh tool instead.')
+      }
+      const sandbox = ctx.get('sandbox')
+      if (sandbox === undefined) throw new Error('pwsh_run: ctx.sandbox is absent, so a persistent session cannot be confined. Mount @deepseek-ai/dsh-sandbox-local, or use the native pwsh tool.')
+      let confined
+      try {
+        confined = await sandbox.confine(plain, policy, signal)
+      } catch (error) {
+        throw new Error(describeConfineFailure(error, policy.workspaceRoot))
+      }
+      return await startSession(ctx.subprocess, { executable, argv: confined.argv, cwd, serverSource: SERVER_SOURCE, label: key, maxOutputBytes })
+    })()
+    pending.catch(() => sessions.delete(key))
+    sessions.set(key, pending)
+
+    if (sessions.size > maxSessions) {
+      const others = [...sessions.entries()].filter(([victim]) => victim !== key)
+      const ages = []
+      for (const entry of others) {
+        let lastUsed = 0
+        try {
+          lastUsed = (await entry[1]).lastUsed
+        } catch {
+          lastUsed = 0
+        }
+        ages.push([entry[0], entry[1], lastUsed])
+      }
+      ages.sort((a, b) => a[2] - b[2])
+      for (const [victimKey, victim] of ages.slice(0, Math.max(0, sessions.size - maxSessions))) {
+        sessions.delete(victimKey)
+        Promise.resolve(victim).then((session) => session.dispose(), () => undefined)
+      }
+    }
+    return await pending
+  }
+
+  // 空闲会话回收，避免常驻进程无限累积。
+  const reaper = setInterval(() => {
+    const now = Date.now()
+    for (const [key, pending] of [...sessions.entries()]) {
+      Promise.resolve(pending).then(async (session) => {
+        if (now - session.lastUsed > idleMs) await evict(key, session)
+      }, () => sessions.delete(key))
+    }
+  }, Math.min(idleMs, 60000))
+  if (typeof reaper.unref === 'function') reaper.unref()
+
+  /** 插件卸载 / 热重载时清干净：停回收器 + 杀掉所有会话。 */
+  ctx.effect(() => () => {
+    clearInterval(reaper)
+    for (const pending of sessions.values()) Promise.resolve(pending).then((session) => session.dispose(), () => undefined)
+    sessions.clear()
+  }, 'pwsh-run.sessions')
+
+  // 更新检查：只读 npm registry 的 dist-tags、只记判决，从不自己安装。
+  // 发现新版本时不改工具描述（描述在注册时就固定了），而是把提示挂在每次调用的
+  // 输出末尾一次——够模型看见，也不至于每次刷。
+  const checker = updateCheck
+    ? new UpdateChecker({
+        log: (line) => {
+          try {
+            ctx.logger?.info?.('pwsh-run: %s', line)
+          } catch {
+            // 日志服务缺席时不影响工具本身。
+          }
+        },
+      })
+    : undefined
+  // 自动更新循环自成一个 effect：它比 checker 多一层「装上即生效」的动作，
+  // 失败要退避、要记装过的版本，这些都在 auto-update.mjs 里。
+  ctx.effect(() => {
+    const stopAuto = autoUpdate && checker !== undefined
+      ? startAutoUpdate(ctx, checker, {
+          log: (line) => { try { ctx.logger?.info?.('pwsh-run: %s', line) } catch { /* 日志缺席不影响更新 */ } },
+          installGate,
+          ...(Number.isSafeInteger(config?.autoUpdateDelayMs) && config.autoUpdateDelayMs >= 0 ? { firstDelayMs: config.autoUpdateDelayMs } : {}),
+        })
+      : undefined
+    return () => stopAuto?.()
+  }, 'pwsh-run.auto-update')
+
+  // 提示用的定时检查只在自动更新关闭时才起：自动更新的循环自己就会调 check()，
+  // 两边都开着等于每 12 小时查两次。
+  ctx.effect(() => {
+    if (checker === undefined || autoUpdate) return undefined
+    checker.start()
+    return () => checker.stop()
+  }, 'pwsh-run.update')
+
+  /**
+   * 更新工具：把「查到」与「装」拆成同一入口的两个动作。
+   *
+   * 为什么要有它
+   *   只把提示挂在 pwsh_run 输出末尾时，模型看见了也无从下手（它拿不到 profile 名，
+   *   也不知道该不该重启）。给出一个能被调用的动作，比给一句话可靠。
+   *
+   * 为什么装这一步不自己下载
+   *   见 update-apply.mjs 的头注释：本插件是 profile 的一个 bundle 依赖，版本钉在
+   *   package.json 与 pnpm-lock.yaml 里，绕开包管理器改文件会让 lockfile 与磁盘不一致。
+   */
+  ctx.effect(() => ctx.tools.register({
+    name: 'pwsh_run_update',
+    description: [
+      'Check for, and optionally install, a newer release of the pwsh_run plugin.',
+      '* action "check" reads the npm registry dist-tags once and reports the verdict; it never installs anything.',
+      '* action "install" hands the pinned version spec (<package>@X.Y.Z) to DSH\'s own plugin manager (the same service the Plugins page uses), which runs pnpm and rolls back on failure.',
+      '* Installing writes the package to the profile. Where the host runs its HMR service, the new code is already live when this returns; otherwise the running process keeps the old modules until DSH restarts. The result says which of the two happened.',
+      '* Only published stable versions are considered; pre-releases are never pushed. The version actually installed is read back from disk, because pnpm\'s minimumReleaseAge policy can install an older release than the one requested.',
+      '* An install replaces this plugin in place, which terminates the persistent pwsh sessions. It is therefore refused while a pwsh_run call is running; retry after that call finishes (the automatic updater applies the same rule on its own).',
+    ].join('\n'),
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['check', 'install'],
+          description: 'check (default): report whether a newer release exists. install: also install the newest release.',
+        },
+      },
+      additionalProperties: false,
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: { text: { type: 'string' } },
+        required: ['text'],
+      },
+      render: (_args, value) => [{ type: 'text', text: value.text }],
+    },
+    async execute(args) {
+      if (checker === undefined) {
+        return { text: 'pwsh_run update checks are disabled in this profile (config.updateCheck: false), so pwsh_run_update has nothing to do.' }
+      }
+      const action = args?.action === 'install' ? 'install' : 'check'
+      const state = await checker.check()
+      const doc = checker.document()
+      const lines = ['state: ' + String(doc.state)]
+      if (doc.running !== undefined) lines.push('running: ' + doc.running)
+      if (doc.latest !== undefined) lines.push('newest release: ' + doc.latest)
+      if (doc.spec !== undefined) lines.push('install spec: ' + doc.spec)
+      if (doc.error !== undefined) lines.push('error: ' + String(doc.error))
+      if (state.state !== 'available') {
+        // failed 与 current 必须分开说：查不到的时候说「已是最新」是句谎话。
+        if (state.state === 'current') {
+          lines.push(action === 'install'
+            ? 'Nothing to install: this is the newest release the source publishes.'
+            : 'No newer release.')
+        }
+        else {
+          // 这条分支上 doc.spec 是 undefined，插值只会印出一个字面占位符，所以给模板。
+          lines.push('Could not reach the npm registry, so whether a newer version exists is unknown. '
+            + 'Run the check again later, or upgrade by hand: dsh plugin --profile <name> add "<package>@X.Y.Z"')
+        }
+        return { text: lines.join('\n') }
+      }
+      if (action === 'check') {
+        lines.push('Run this again with action "install", or run: dsh plugin --profile <name> add "' + String(doc.spec) + '"')
+        return { text: lines.join('\n') }
+      }
+      // 装之前先问一句值不值得装：磁盘上已经是这个版本、或者这个 tag 的包根本没改过版本号，
+      // 装下去只会被 plugin-manager 判 already-installed。判掉后照实说清是哪一种。
+      const unnecessary = preflightInstall(ctx, checker, String(doc.spec))
+      if (unnecessary !== null) {
+        lines.push('install: ' + unnecessary.outcome)
+        lines.push(unnecessary.text)
+        return { text: lines.join('\n') }
+      }
+      // 安装会热替换本插件，从而 dispose 掉所有常驻会话。正有调用在跑时先不装：
+      // 掐断别人跑到一半的脚本，代价远大于晚几十秒。
+      if (!beginInstall()) {
+        lines.push('install: postponed')
+        lines.push('A pwsh_run call is running right now, and installing would terminate its session mid-script. '
+          + 'Retry once that call has finished; auto-update performs this same check on its own.')
+        return { text: lines.join('\n') }
+      }
+      let outcome
+      try {
+        outcome = await installReleaseLive(ctx, String(doc.spec), { requestId: 'pwsh-run-update' })
+      } finally {
+        endInstall()
+      }
+      lines.push('install: ' + outcome.outcome)
+      lines.push(outcome.text)
+      if (outcome.installedVersion !== undefined && outcome.installedVersion !== doc.latest) {
+        lines.push('Installed version on disk: ' + outcome.installedVersion + ' (requested ' + String(doc.latest) + ').')
+      }
+      if (outcome.ok !== true && doc.spec !== undefined) lines.push('Manual path: dsh plugin --profile <name> add "' + String(doc.spec) + '"')
+      return { text: lines.join('\n') }
+    },
+  }), 'pwsh-run.update-tool')
+
+  /** 一条调用的实体；activeRuns 由注册处的 execute 在外面加减。 */
+  const runScript = async (args, exec) => {
+    await waitForInstall()
+    const requested = Number.isFinite(args?.timeoutMs) && args.timeoutMs > 0 ? Math.trunc(args.timeoutMs) : defaultTimeoutMs
+    const key = sessionKey(exec)
+    const workdir = typeof args?.workdir === 'string' && args.workdir.length > 0 ? args.workdir : undefined
+
+    // workdir 通过 Set-Location 生效（会话有状态，所以下一次调用会继承）。
+    const script = workdir === undefined
+      ? args.script
+      : 'Set-Location -LiteralPath ' + psLiteral(workdir) + " -ErrorAction Stop\n" + args.script
+
+    let session
+    try {
+      session = await acquire(key, workdir, exec?.agent, exec?.signal)
+    } catch (error) {
+      // acquire 里已经写好人话的错误（沙箱缺席、read-only、confine 失败）不再套第二层前缀。
+      // 用 \b 而不是 'pwsh_run '：几条自带文案是 'pwsh_run: ...' 冒号收尾，带空格的匹配会漏掉它们。
+      const message = String(error?.message ?? error)
+      throw new Error(/^pwsh_run\b/.test(message) ? message : 'pwsh_run could not start a session: ' + message)
+    }
+
+    const local = withTimeout(exec?.signal, requested + RESPONSE_GRACE_MS)
+    let expired = false
+    const onAbort = () => { expired = true }
+    local.addEventListener('abort', onAbort, { once: true })
+
+    let response = null
+    try {
+      response = await Promise.race([
+        session.run(script, requested),
+        new Promise((resolve) => {
+          local.addEventListener('abort', () => resolve(null), { once: true })
+        }),
+      ])
+    } catch (error) {
+      // 会话中途死亡：清掉，下一次调用自动重建。
+      await evict(key, session)
+      const message = String(error)
+      const note = session.dead ? '[' + message + '; a new session starts on the next call]' : '[' + message + ']'
+      return { text: note }
+    } finally {
+      local.removeEventListener('abort', onAbort)
+    }
+
+    const notes = []
+    if (response?.truncated === true) notes.push('[output truncated at ' + String(maxOutputBytes) + ' bytes; redirect to a file if you need it all]')
+    if (response === null || expired) {
+      // 服务端没能在预算内回话：整个进程杀掉重建，不让一条调用拖垮后续。
+      await evict(key, session)
+      notes.push(exec?.signal?.aborted === true
+        ? '[cancelled; the session was terminated and is rebuilt on the next call]'
+        : '[no response from the pwsh session within ' + String(Math.round(requested / 1000)) + 's; the session was terminated and is rebuilt on the next call]')
+    } else if (session.dead) {
+      await evict(key, session)
+      notes.push('[' + String(session.deathReason) + '; a new session starts on the next call]')
+    } else if (response.timedOut) {
+      // 服务端 Stop() 能打断脚本，但脚本内 Start-Process 起的子进程不会随之回收
+      // （实测子进程仍存活）。杀掉整个会话才能靠 Job Object 连带清干净。
+      await evict(key, session)
+      notes.push('[timed out after ' + String(Math.round(requested / 1000)) + 's; partial output above; the session was terminated and is rebuilt on the next call]')
+    }
+
+    const body = []
+    for (const line of response?.out ?? []) body.push(line)
+    for (const line of response?.warn ?? []) body.push('WARNING: ' + line)
+    for (const line of response?.verbose ?? []) body.push('VERBOSE: ' + line)
+    if (response?.sentinel === 'threw') body.push('[script threw]')
+    // 更新提示只在第一次查到新版本时挂一行，之后不再刷。自动更新关掉时给出可照做的命令，
+    // 打开时说清楚它自己会装——否则模型会把这个版本当成「需要人工干预」。
+    const fresh = checker?.announce
+    if (fresh !== undefined && autoUpdate === false) {
+      notes.push('[a newer pwsh-run release exists: ' + fresh.latest + ' (running ' + String(checker?.version ?? '?') +
+        '). Install it with dsh plugin --profile <name> add "' + fresh.spec + '". ' +
+        'Auto-update is off in this profile (config.autoUpdate: false).]')
+    }
+    const text = [body.join('\n')]
+      .concat(response?.err ?? [])
+      .concat(response?.exceptions ?? [])
+      .concat(response?.fatal ?? [])
+      .join('\n')
+    const denial = describeExecDenial(text)
+    if (denial !== null) notes.push(denial)
+    const all = [text].concat(notes).filter((part) => part.length > 0).join('\n')
+    return { text: all.length > 0 ? all : '(no output)' }
+  }
+
+  // 工具注册也要挂到 effect 上：live patchReload 会重新 apply 本模块，
+  // 旧注册不撤的话 ctx.tools.register 会抛 "already registered"。
+  ctx.effect(() => ctx.tools.register({
+    name: 'pwsh_run',
+    description: [
+      'Run a PowerShell script in a **persistent** pwsh 7 session.',
+      '* Send the script body verbatim: do NOT escape $, do NOT wrap it in pwsh -c, do NOT add shell quotes. There is no shell in between — the script goes straight to pwsh over stdin.',
+      '* Prefer this over the pwsh tool when the script contains $variables, here-strings (@\'...\'@ / @"..."@), backticks, quotes, non-ASCII text, or is longer than a few thousand characters. The pwsh tool is capped by the Windows command line (~32K) and every call is a fresh process.',
+      '* State persists across calls in the same session: variables, current directory, $env: entries and imported modules. Do not assume a clean slate; reset explicitly when you need to.',
+      '* Output ordering is preserved and streams are labelled (stdout / error / warning / verbose).',
+      '* Each call times out after ' + String(Math.round(defaultTimeoutMs / 1000)) + 's by default (override with timeoutMs). On timeout the whole session process is terminated and rebuilt — persisted state is lost.',
+      '* exit N inside the script only ends that call; its exit code is NOT observable. Use $LASTEXITCODE or Write-Output instead.',
+      '* Sandbox: the persistent process is confined once at launch, and because the Windows ACL restricted token applies to the whole process, every later read/write in this session obeys the same workspace boundary as the native pwsh tool. In read-only mode this tool refuses to start (a persistent session needs FullLanguage) — use the native pwsh tool there.',
+      '* Not for interactive programs or anything that needs a TTY.',
+    ].join('\n'),
+    parameters,
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: { text: { type: 'string' } },
+        required: ['text'],
+      },
+      render: (_args, value) => [{ type: 'text', text: value.text }],
+    },
+    async execute(args, exec) {
+      // 自动更新与手动安装都要先看这个计数：热替换会 dispose 全部会话，
+      // 正跑着的脚本会被连人带马掐断。
+      activeRuns += 1
+      try {
+        return await runScript(args, exec)
+      } finally {
+        activeRuns -= 1
+      }
+    },
+  }), 'pwsh-run.tool')
+}