dsh-ssh-workbench 1.6.4 → 1.7.0

package/lib/core/remote-bash.js

@@ -1,337 +0,0 @@
-/**
- * Route the native `bash` tool to a managed server.
- *
- * `tools/execute` is DSH's around-dispatch waterfall. This handler returns a
- * replacement result for exactly one tool — the built-in `bash` — and only
- * while the session has an active managed target; every other call falls
- * through with `next()`. The replacement value is the native bash foreground
- * value, so the registry validates it against the built-in output schema and
- * renders it with the built-in terminal renderer: no shadow tool, no schema
- * copy, no custom rendering.
- */
-import { describeResultOutcome } from './activity.js'
-import { buildPosixBackgroundCommand, parseBackgroundStart, renderBackgroundStart } from './background.js'
-import { effectiveDialect } from './dialect.js'
-import { quotePosix } from './posix-quote.js'
-import { findTarget } from './targets.js'
-
-export const BASH_TOOL_NAME = 'bash'
-
-const MIN_TIMEOUT_MS = 1000
-const POSIX_PLATFORM = 'posix'
-
-export { quotePosix }
-
-/**
- * Wrap a remote command with the remote `timeout` utility.
- *
- * A client-side timeout only closes the SSH channel; a process that ignores
- * SIGHUP (nohup/background) keeps running on the server. Wrapping the command
- * gives the remote side the same deadline: coreutils `timeout` runs the
- * managed command in its own process group and signals the whole group, so
- * when the client gives up the remote work stops too. `kill` adds `-k <n>`
- * (KILL after TERM); `basic` sends TERM only; `none` (or an unknown
- * capability) leaves the command untouched.
- *
- * The wrapper re-enters the remote login shell (`<shell> -c`) so shell
- * semantics do not change. The shell path comes from the capability probe and
- * is referenced as a quoted literal, so this also works on fish/csh (no POSIX
- * `${SHELL:-...}` expansion). The command itself is single-quote escaped and
- * therefore expanded exactly once, inside that shell.
- *
- * @param {string} command
- * @param {number} timeoutMs
- * @param {'kill'|'basic'|'none'|{mode?: string, shell?: string}} [capability]
- * @param {{ killAfterMs?: number }} [options]
- */
-export function wrapRemoteTimeout(command, timeoutMs, capability = 'none', options = {}) {
-  const info = typeof capability === 'string' ? { mode: capability } : (capability ?? {})
-  const mode = info.mode === 'kill' || info.mode === 'basic' ? info.mode : 'none'
-  if (mode === 'none') return String(command ?? '')
-  const shell = typeof info.shell === 'string' && info.shell.startsWith('/') ? info.shell : '/bin/sh'
-  const killAfterMs = Number.isFinite(options.killAfterMs) ? options.killAfterMs : 5000
-  const killSeconds = Math.max(0, Math.ceil(killAfterMs / 1000))
-  const seconds = Math.max(1, Number(timeoutMs) / 1000)
-  const suffix = mode === 'kill' && killSeconds > 0 ? `-k ${killSeconds} ` : ''
-  return `timeout ${suffix}${seconds} ${quotePosix(shell)} -c ${quotePosix(command)}`
-}
-
-/**
- * Turn the model-facing `workdir` into a shell prefix and the value's cwd label.
- *
- * The remote shell starts in the login home; absolute paths are used verbatim,
- * `~`/`~/x` and relative paths are anchored at `$HOME`.
- *
- * @returns {{ command: string, cwd: string } | { error: string }}
- */
-export function applyWorkdir(command, workdir) {
-  const raw = typeof workdir === 'string' ? workdir.trim() : ''
-  const body = String(command ?? '')
-  if (!raw) return { command: body, cwd: '~' }
-  if (raw.includes('\n') || raw.includes('\r')) return { error: 'workdir must not contain newlines' }
-  if (raw.startsWith('~')) {
-    const rest = raw === '~' ? '' : raw.slice(1)
-    if (rest !== '' && !rest.startsWith('/')) return { error: 'workdir must be an absolute path, ~/path, or a relative path' }
-    const target = rest === '' ? '"$HOME"' : `"$HOME"${quotePosix(rest)}`
-    return { command: `cd -- ${target} && ${body}`, cwd: raw }
-  }
-  if (raw.startsWith('/')) {
-    return { command: `cd -- ${quotePosix(raw)} && ${body}`, cwd: raw }
-  }
-  return { command: `cd -- "$HOME"/${quotePosix(raw)} && ${body}`, cwd: `~/${raw}` }
-}
-
-/** Effective timeout for one call, clamped to the configured ceiling. */
-export function resolveTimeoutMs(args, config) {
-  const ceiling = Number.isInteger(config?.maxCommandTimeoutMs) ? config.maxCommandTimeoutMs : 30 * 60 * 1000
-  const requested = Number.isInteger(args?.timeoutMs) ? args.timeoutMs : undefined
-  const fallback = Number.isInteger(config?.commandTimeoutMs) ? config.commandTimeoutMs : 120000
-  const value = requested ?? fallback
-  return Math.max(MIN_TIMEOUT_MS, Math.min(value, ceiling))
-}
-
-/**
- * Map one runtime exec result onto the native bash foreground value.
- * Non-zero exits are normal results; only "the command never ran" becomes an
- * error result on the caller side.
- */
-export function toBashValue(result, { cwd, timeoutMs }) {
-  const stdout = typeof result?.stdout === 'string' ? result.stdout : ''
-  const stderr = typeof result?.stderr === 'string' ? result.stderr : ''
-  const exitCode = Number.isInteger(result?.exitCode) ? result.exitCode : null
-  const signal = typeof result?.signal === 'string' && result.signal.length > 0 ? result.signal : null
-  return {
-    kind: 'foreground',
-    cwd,
-    exitCode,
-    signal,
-    timedOut: result?.outcome === 'timeout',
-    aborted: result?.outcome === 'cancelled',
-    timeoutMs,
-    stdout: { text: stdout, truncated: result?.truncated?.stdout === true },
-    stderr: { text: stderr, truncated: result?.truncated?.stderr === true },
-  }
-}
-
-/**
- * Whether a runtime result means the command never reached the remote shell.
- * Timeouts and aborts are real command outcomes (timedOut / aborted on the
- * native value), not transport failures.
- */
-export function isTransportFailure(result) {
-  if (!result || typeof result !== 'object') return true
-  if (result.exitCode !== null && result.exitCode !== undefined) return false
-  if (typeof result.signal === 'string' && result.signal.length > 0) return false
-  return result.outcome === 'failed'
-}
-
-/** Build the structured error result the pipeline accepts for a failed call. */
-export function createErrorResult(message, code = 'SSH_FAILED') {
-  const text = String(message ?? 'remote bash failed')
-  return {
-    isError: true,
-    content: [{ type: 'text', text: `Error: ${code}: ${text}` }],
-    error: { message: text, info: { name: 'SshOpsError', code } },
-  }
-}
-
-/**
- * @param {object} deps
- * @param {object} deps.runtime SSH runtime facade (`createSshRuntime`)
- * @param {object} deps.targets per-session target store
- * @param {object} deps.config resolved plugin config
- * @param {() => object[]} deps.loadInventory
- * @param {(entry: object) => void} [deps.recordActivity]
- * @returns {(exec: object, next: () => Promise<object>) => Promise<object>}
- */
-export function createRemoteBashRouter({ runtime, targets, config, loadInventory, recordActivity } = {}) {
-  return async function remoteBashRouter(exec, next) {
-    if (!exec || exec.name !== BASH_TOOL_NAME) return next()
-    const session = exec.agent?.session
-    const key = session?.id ?? exec.agent?.id
-    const binding = typeof key === 'string' ? targets?.get(key) : undefined
-    if (!binding || !binding.active) {
-      // Several `@server` mentions clear the active target. Running bash locally
-      // in that state would execute commands meant for a server on the DSH host,
-      // so make the model choose a target first.
-      if (binding && Array.isArray(binding.candidates) && binding.candidates.length > 1) {
-        return createErrorResult(
-          `several servers were mentioned in this session (${binding.candidates.join(', ')}); ` +
-            'call ssh_workbench_target({ server: "<name>" }) before running bash, or server: "local" to run locally',
-          'TARGET_NOT_SELECTED',
-        )
-      }
-      return next()
-    }
-
-    const args = exec.arguments ?? {}
-    const command = typeof args.command === 'string' ? args.command : ''
-    if (!command.trim()) return next()
-
-    let servers
-    try {
-      servers = loadInventory()
-    } catch (error) {
-      return createErrorResult(`cannot read the managed server inventory: ${describeError(error)}`, 'INVENTORY_UNAVAILABLE')
-    }
-    const server = findTarget(servers, binding.active)
-    if (server === undefined) {
-      return createErrorResult(
-        `target "${binding.active}" is no longer in the managed inventory; call ${'ssh_workbench_target'} to pick another target or "local"`,
-        'TARGET_NOT_FOUND',
-      )
-    }
-    if (server.enabled === false) {
-      return createErrorResult(
-        `target "${server.name}" is disabled; call ssh_workbench_target to pick another target or "local"`,
-        'TARGET_DISABLED',
-      )
-    }
-    if (effectiveDialect(server) !== POSIX_PLATFORM) {
-      return createErrorResult(
-        `target "${server.name}" is a Windows server; the native bash tool only runs POSIX commands — use remote_pwsh for Windows targets`,
-        'TARGET_PLATFORM_UNSUPPORTED',
-      )
-    }
-
-    const workdir = applyWorkdir(command, args.workdir)
-    if (workdir.error !== undefined) return createErrorResult(workdir.error, 'INVALID_WORKDIR')
-
-    // A detached command returns only remote facts that survive across
-    // transports: pid + log file. It is not registered in DSH's local jobs.
-    if (args.run_in_background === true) {
-      const startTimeout = Math.min(resolveTimeoutMs(args, config), 30000)
-      let start
-      try {
-        start = await runtime.exec(server, buildPosixBackgroundCommand(workdir.command), {
-          timeoutMs: startTimeout,
-          signal: exec.signal,
-          readOnly: false,
-          cap: Number.isInteger(config?.maxOutputBytes) ? config.maxOutputBytes : undefined,
-          stderrCap: Number.isInteger(config?.maxStderrBytes) ? config.maxStderrBytes : undefined,
-        })
-      } catch (error) {
-        return createErrorResult(describeError(error), 'SSH_EXEC_FAILED')
-      }
-      try {
-        recordActivity?.({ kind: 'exec', server: server.name, summary: `[background] ${command.slice(0, 190)}`, outcome: describeResultOutcome(start) })
-      } catch {
-        // Activity recording is best effort.
-      }
-      if (isTransportFailure(start)) {
-        const detail = typeof start?.stderr === 'string' && start.stderr.trim() ? start.stderr.trim() : 'remote execution failed'
-        return createErrorResult(detail, start?.errorCode ?? 'SSH_EXEC_FAILED')
-      }
-      const started = parseBackgroundStart(start.stdout)
-      if (started.pid === undefined) {
-        const detail = String(start?.stderr ?? '').trim() || String(start?.stdout ?? '').trim()
-        return createErrorResult(`background start failed${detail ? `: ${detail}` : ''}`, 'REMOTE_BACKGROUND_FAILED')
-      }
-      const text = renderBackgroundStart({
-        pid: started.pid,
-        log: started.log,
-        errLog: started.errLog,
-        target: `${server.name} (${server.username}@${server.host}:${server.port})`,
-        command,
-        dialect: 'posix',
-      })
-      const synthetic = {
-        outcome: 'success',
-        exitCode: 0,
-        signal: null,
-        stdout: text,
-        stderr: '',
-        truncated: { stdout: false, stderr: false },
-      }
-      return { value: toBashValue(synthetic, { cwd: `${server.name}:${workdir.cwd}`, timeoutMs: startTimeout }) }
-    }
-
-    const timeoutMs = resolveTimeoutMs(args, config)
-
-    // Detect (and cache) whether the server can enforce a remote deadline, so
-    // a timed-out call also stops the remote work instead of leaving it behind.
-    let capability = { mode: 'none', shell: '/bin/sh' }
-    try {
-      if (typeof runtime.timeoutGuard === 'function') {
-        const probed = await runtime.timeoutGuard(server)
-        capability = typeof probed === 'string' ? { mode: probed } : (probed ?? capability)
-      }
-    } catch {
-      capability = { mode: 'none', shell: '/bin/sh' }
-    }
-    const remoteCommand = wrapRemoteTimeout(workdir.command, timeoutMs, capability, {
-      killAfterMs: config?.timeoutKillAfterMs,
-    })
-
-    let result
-    try {
-      result = await runtime.exec(server, remoteCommand, {
-        timeoutMs,
-        signal: exec.signal,
-        readOnly: false,
-        cap: Number.isInteger(config?.maxOutputBytes) ? config.maxOutputBytes : undefined,
-        stderrCap: Number.isInteger(config?.maxStderrBytes) ? config.maxStderrBytes : undefined,
-      })
-    } catch (error) {
-      return createErrorResult(describeError(error), 'SSH_EXEC_FAILED')
-    }
-
-    try {
-      recordActivity?.({
-        kind: 'exec',
-        server: server.name,
-        summary: command.slice(0, 200),
-        outcome: describeResultOutcome(result),
-      })
-    } catch {
-      // Activity recording is best effort.
-    }
-
-    if (isTransportFailure(result)) {
-      const code = typeof result?.errorCode === 'string' && result.errorCode ? result.errorCode : 'SSH_EXEC_FAILED'
-      const detail = typeof result?.stderr === 'string' && result.stderr.trim() ? result.stderr.trim() : 'remote execution failed'
-      const suggestion = typeof result?.suggestedAction === 'string' && result.suggestedAction ? `\n${result.suggestedAction}` : ''
-      return createErrorResult(`${detail}${suggestion}`, code)
-    }
-
-    // The cwd label is also what the native Bash card shows in its expanded
-    // prompt; prefixing the target makes a card self-describing in multi-target
-    // sessions without shadowing DSH's shipped Bash renderer.
-    let value = toBashValue(result, { cwd: `${server.name}:${workdir.cwd}`, timeoutMs })
-    const notices = []
-    // One line after each target change: a card-level "where did this run" hint.
-    if (binding.notifiedVersion !== binding.version && typeof targets?.markNotified === 'function') {
-      notices.push(`[remote] target: ${server.name} (${server.username}@${server.host}:${server.port})`)
-      targets.markNotified(key, binding.version)
-    }
-    if (result?.outcome === 'timeout') {
-      notices.push(
-        capability.mode === 'none'
-          ? '[remote] client-side timeout only: this server has no usable `timeout` utility, so the remote process may still be running.'
-          : `[remote] timeout: the remote command group was terminated (SIGTERM${capability.mode === 'kill' ? ', KILL after the remote deadline' : ''}).`,
-      )
-    }
-    if (result?.outcome === 'cancelled') {
-      notices.push(
-        capability.mode === 'none'
-          ? '[remote] cancelled: the SSH channel was closed, but this server has no usable `timeout` utility, so the remote process may still be running.'
-          : '[remote] cancelled: the SSH channel was closed; the remote wrapper terminates the command at its deadline if it is still running.',
-      )
-    }
-    if (args.sandbox_permissions !== undefined || args.justification !== undefined) {
-      notices.push('[remote] sandbox_permissions does not apply to managed servers; the command ran over SSH.')
-    }
-    if (notices.length > 0) {
-      const text = value.stderr.text
-      value = {
-        ...value,
-        stderr: { ...value.stderr, text: `${text}${text ? '\n' : ''}${notices.join('\n')}` },
-      }
-    }
-    return { value }
-  }
-}
-
-function describeError(error) {
-  return error instanceof Error ? error.message : String(error)
-}

package/lib/core/server-reference.js

@@ -1,299 +0,0 @@
-/**
- * Target context for @server mentions.
- *
- * The composer inserts an `@name` chip as plain text, so the model can read it
- * as a teammate mention. This module turns matches against the managed
- * inventory into (a) the session's active remote target and (b) one compact
- * user-role context message that tells the model where `bash` runs and how to
- * switch targets.
- *
- * The injected message enters the same step (`agent/pre-step` replaces the
- * messages that enter a step), which `agent.inject()` cannot promise because it
- * splices into the next step. The decision is spread so fields such as
- * `startsRequestSeries` survive.
- *
- * Scope: every agent mode; no preset gating.
- */
-import { randomUUID } from 'node:crypto'
-
-import { effectiveDialect } from './dialect.js'
-import { loadServers } from './store.js'
-import {
-  LOCAL_TARGET,
-  TARGET_CONTEXT_KIND,
-  TARGET_TOOL_NAME,
-  createTargetStore,
-  extractServerMentions,
-  extractUserText,
-  lastHumanMessage,
-} from './targets.js'
-
-export { TARGET_CONTEXT_KIND, TARGET_TOOL_NAME }
-
-function describeError(error) {
-  return error instanceof Error ? error.message : String(error)
-}
-
-function serverLine(server) {
-  const target = `${server.username ?? 'root'}@${server.host}:${server.port ?? 22}`
-  const state = server.enabled === false ? ' · disabled' : ''
-  const dialect = effectiveDialect(server)
-  return `- ${server.name} — ${target} · ${dialect}${state}${factsSummary(server)}`
-}
-
-/** Compact facts summary (hostname only: stable, not a stale capacity snapshot). */
-function factsSummary(server) {
-  const facts = server?.facts
-  if (!facts || typeof facts !== 'object') return ''
-  const hostname = typeof facts.hostname === 'string' ? facts.hostname.trim() : ''
-  return hostname ? ` · ${hostname}` : ''
-}
-
-/**
- * Resolve the copy dialect for one Host.
- *
- * `remoteToolName` is the tool that actually executes on the target: the native
- * `bash` tool on POSIX Hosts, the plugin-owned `remote_bash` tool on Windows
- * Hosts (where DSH ships no bash). The context must describe the tool the model
- * really has, never a tool name that cannot exist on this Host.
- */
-function contextOptions(options = {}) {
-  const hostOs = options.hostPlatform === 'win32' ? 'win32' : 'posix'
-  const remoteToolName =
-    typeof options.remoteToolName === 'string' && options.remoteToolName.length > 0
-      ? options.remoteToolName
-      : hostOs === 'win32'
-        ? 'remote_bash'
-        : 'bash'
-  const windowsToolName =
-    typeof options.windowsToolName === 'string' && options.windowsToolName.length > 0 ? options.windowsToolName : 'remote_pwsh'
-  return { hostOs, remoteToolName, windowsToolName }
-}
-
-/**
- * Render the model-facing target context.
- * @param {{ active: string|null, candidates: string[] }} state
- * @param {object[]} servers managed inventory
- * @param {{ hostPlatform?: 'win32'|'posix', remoteToolName?: string, windowsToolName?: string }} [options]
- */
-export function renderTargetContext(state, servers, options = {}) {
-  const { hostOs, remoteToolName, windowsToolName } = contextOptions(options)
-  const byName = new Map()
-  for (const server of servers ?? []) byName.set(server.name, server)
-  const lines = ['[ssh-workbench] Managed server context:']
-  if (typeof state?.active === 'string' && state.active.length > 0) {
-    const server = byName.get(state.active)
-    lines.push(server ? serverLine(server) : `- ${state.active}`)
-    const activeDialect = effectiveDialect(server)
-    if (activeDialect === 'windows') {
-      lines.push(
-        `The ${windowsToolName} tool runs PowerShell commands on ${state.active} over SSH; pass ${windowsToolName}.workdir to change its working directory.`,
-      )
-      lines.push(`The native ${hostOs === 'win32' ? 'pwsh' : 'bash'} tool always runs on the local DSH host: never use it for commands meant for ${state.active}.`)
-      lines.push(
-        `read/write/edit/glob/grep always run on the local DSH host: never use write/edit for remote files — change them through ${windowsToolName} or the GUI SFTP panel.`,
-      )
-      lines.push(`Do not use ssh/scp inside ${windowsToolName} to reach other servers; switch targets with ${TARGET_TOOL_NAME}.`)
-      lines.push('After a state change, verify the result before reporting; exit code 0 does not prove success.')
-      lines.push(`Switch target: ${TARGET_TOOL_NAME}({ server: "<name>" }); detach: server: "${LOCAL_TARGET}".`)
-      return lines.join('\n')
-    }
-    if (hostOs === 'win32') {
-      lines.push(
-        `The ${remoteToolName} tool runs POSIX shell commands on ${state.active} over SSH; pass ${remoteToolName}.workdir to change its working directory.`,
-      )
-      lines.push(`The native pwsh tool always runs on the local DSH host: never use it for commands meant for ${state.active}.`)
-      lines.push(
-        `read/write/edit/glob/grep always run on the local DSH host: never use write/edit for remote files — change them through ${remoteToolName} (heredoc, sed -i) or the GUI SFTP panel.`,
-      )
-      lines.push(`Do not use ssh/scp inside ${remoteToolName} to reach other servers; switch targets with ${TARGET_TOOL_NAME}.`)
-    } else {
-      lines.push(`The ${remoteToolName} tool runs on ${state.active}; pass ${remoteToolName}.workdir to change its working directory.`)
-      lines.push(
-        `read/write/edit/glob/grep always run on the local DSH host: never use write/edit for remote files — change them through ${remoteToolName} (heredoc, sed -i) or the GUI SFTP panel.`,
-      )
-      lines.push(`Do not use ssh/scp inside ${remoteToolName} to reach other servers; switch targets with ${TARGET_TOOL_NAME}.`)
-    }
-    lines.push('After a state change, verify the result before reporting; exit code 0 does not prove success.')
-    lines.push(`Switch target: ${TARGET_TOOL_NAME}({ server: "<name>" }); detach: server: "${LOCAL_TARGET}".`)
-    return lines.join('\n')
-  }
-  const candidates = Array.isArray(state?.candidates) ? state.candidates : []
-  const listed = candidates.map((name) => byName.get(name)).filter(Boolean)
-  for (const server of listed) lines.push(serverLine(server))
-  if (listed.length === 0) lines.push(`- (unresolved: ${candidates.join(', ')})`)
-  if (hostOs === 'win32') {
-    lines.push(
-      `The native pwsh tool runs on the local DSH host; ${remoteToolName} only runs after you choose a target with ${TARGET_TOOL_NAME}({ server: "<name>" }).`,
-    )
-    lines.push(
-      `read/write/edit/glob/grep always run on the local DSH host: remote files are only reachable through ${remoteToolName}.`,
-    )
-  } else {
-    lines.push(
-      `${remoteToolName} still runs on the local DSH host until you choose a target with ${TARGET_TOOL_NAME}({ server: "<name>" }).`,
-    )
-    lines.push(`read/write/edit/glob/grep always run on the local DSH host: remote files are only reachable through ${remoteToolName}.`)
-  }
-  return lines.join('\n')
-}
-
-/**
- * Build one user-role context message, preferring the host's message factory.
- * `@` symbols are avoided so this message can never be re-matched as a mention.
- */
-export function buildTargetContextMessage(state, servers, createUserMessage, options = {}) {
-  const text = renderTargetContext(state, servers, options)
-  const source = {
-    kind: TARGET_CONTEXT_KIND,
-    form: 'notice',
-    summary: state?.active ? `remote target: ${state.active}` : 'remote target not selected',
-  }
-  const input = { content: [{ type: 'text', text }], source }
-  if (typeof createUserMessage === 'function') return createUserMessage(input)
-  return { role: 'user', id: `ssh-workbench-target-${randomUUID()}`, ...structuredClone(input) }
-}
-
-/**
- * Install the target binding + context provider.
- *
- * @param {object} ctx plugin context
- * @param {{
- *   enabled?: boolean,
- *   remoteAvailable?: boolean,
- *   hostPlatform?: 'win32'|'posix',
- *   remoteToolName?: string,
- *   windowsToolName?: string,
- *   ensureDialect?: (server: object) => Promise<string|undefined>,
- *   targets?: object,
- *   loadInventory?: () => object[],
- *   createUserMessage?: Function,
- * }} [options]
- */
-export function installTargetContext(ctx, options = {}) {
-  const enabled = options.enabled !== false
-  const remoteAvailable = options.remoteAvailable !== false
-  const contextOptions = {
-    hostPlatform: options.hostPlatform,
-    remoteToolName: options.remoteToolName,
-    windowsToolName: options.windowsToolName,
-  }
-  const loadInventory = options.loadInventory ?? loadServers
-  const targets = options.targets ?? createTargetStore({ loadInventory })
-  const warn = (message) => {
-    try {
-      ctx?.logger?.warn?.(`dsh-ssh-workbench: ${message}`)
-    } catch {
-      // Logging must never fail the plugin.
-    }
-  }
-  if (!ctx || typeof ctx.on !== 'function') return { targets }
-
-  let factory = options.createUserMessage
-  const messageFactory = async () => {
-    if (factory !== undefined) return factory
-    try {
-      const mod = await import('@deepseek-ai/dsh-llm')
-      factory = typeof mod.createUserMessage === 'function' ? mod.createUserMessage : null
-    } catch {
-      factory = null
-    }
-    return factory
-  }
-
-  const handler = async (payload, next) => {
-    const decision = await next()
-    try {
-      if (!decision || decision.kind === 'reject' || payload?.signal?.aborted) return decision
-      if (enabled === false) return decision
-      // Never describe a remote world the Host cannot execute in: without a
-      // working remote tool the model must keep treating every tool as local.
-      if (!remoteAvailable) return decision
-      const agent = payload?.agent
-      const session = agent?.session
-      const key = session?.id ?? agent?.id
-      if (typeof key !== 'string' || key.length === 0) return decision
-      let servers = loadInventory()
-      // Restore a resumed Session's target from its durable human messages once;
-      // deriveMessages() is intentionally skipped on every later step.
-      if (targets.get(key)?.seeded !== true) {
-        try {
-          const history = typeof session?.deriveMessages === 'function' ? session.deriveMessages() : []
-          targets.ensureSeeded(key, history, servers)
-        } catch {
-          targets.ensureSeeded(key, [], servers)
-        }
-      }
-      const human = lastHumanMessage(decision.messages)
-      const mentions = human ? extractServerMentions(extractUserText(human), servers) : []
-      const state = targets.bindMentions(key, mentions)
-      if (!state) return decision
-      // Describe the target in its real dialect. A fresh record may not have a
-      // probe result yet; probing here (bounded) avoids telling the model to
-      // use a POSIX shell against a Windows host for the whole first turn.
-      const activeServer = state.active ? servers.find((entry) => entry.name === state.active) : undefined
-      if (activeServer && typeof options.ensureDialect === 'function' && !activeServer.facts?.dialect) {
-        try {
-          await Promise.race([
-            Promise.resolve().then(() => options.ensureDialect(activeServer)),
-            new Promise((resolve) => {
-              const timer = setTimeout(resolve, 2500)
-              timer.unref?.()
-            }),
-          ])
-          servers = loadInventory()
-        } catch {
-          // Keep the record hint when probing fails.
-        }
-      }
-      const needsChoice = state.candidates.length > 1 && !state.active
-      if (!state.active && !needsChoice) return decision
-      const changed = state.version !== state.injectedVersion
-      const firstStep = payload?.step === 1
-      if (!changed) {
-        if (!firstStep) return decision
-        // One context message per turn is enough while it is still present in
-        // the step messages (it is committed to the session like other runtime
-        // context). Re-inject after compaction or when the target changed.
-        const hasContext = decision.messages.some((message) => message?.source?.kind === TARGET_CONTEXT_KIND)
-        if (hasContext) return decision
-      }
-      const message = buildTargetContextMessage(state, servers, await messageFactory(), contextOptions)
-      targets.markInjected(key, state.version)
-      return { ...decision, messages: [...decision.messages, message] }
-    } catch (error) {
-      warn(`target context skipped: ${describeError(error)}`)
-      return decision
-    }
-  }
-
-  const offPreStep = ctx.on('agent/pre-step', handler, { prepend: true })
-  const offDisposed = ctx.on('agent/disposed', (disposed) => {
-    try {
-      const session = disposed?.agent?.session
-      const key = session?.id ?? disposed?.agent?.id
-      if (typeof key === 'string') targets.clear(key)
-    } catch {
-      // Best effort cleanup.
-    }
-  })
-  if (typeof ctx.effect === 'function') {
-    ctx.effect(
-      () => () => {
-        try {
-          offPreStep?.()
-        } catch {
-          // Disposal is best effort.
-        }
-        try {
-          offDisposed?.()
-        } catch {
-          // Disposal is best effort.
-        }
-        targets.clearAll?.()
-      },
-      'dsh-ssh-workbench: target context',
-    )
-  }
-  return { targets, offPreStep, offDisposed }
-}