@wingsbutterfly/dsh-rtk 0.1.0

package/src/index.ts

@@ -0,0 +1,431 @@
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { PostToolDecision, ToolDispatchExecution, ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools'
+import type { CommandRuntime } from '@deepseek-ai/dsh-commands'
+import type { SettingsProvider, SettingsScope } from '@deepseek-ai/dsh-settings'
+import type { SystemPrompt } from '@deepseek-ai/dsh-system-prompt'
+
+import { Config, normalizeConfig, type RtkConfig } from './config.js'
+import { READ_COMPACTION_BANNER_PREFIX, compactToolResult } from './compact/index.js'
+import { parseBashResult, renderBashResult } from './compact/dsh-result.js'
+import { createMetricsTracker } from './metrics.js'
+import { createRtkCommand } from './command.js'
+import { resolveRtkExecutable, runExecutable } from './rtk-executable.js'
+import { applyRtkHistoryScope, resolveRtkRewrite, type ShellKind } from './rtk-rewrite.js'
+import { isStatusStale, shouldRequireRtkAvailability, shouldSkipRewrite, type RtkRuntimeStatus } from './runtime-guard.js'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'rtk'
+
+/**
+ * The tool runtime is a hard dependency: both halves of this plugin are
+ * `tools/*` listeners, and without the registry there is nothing to rewrite or
+ * compact.
+ *
+ * `settings` is declared too, and not because the plugin cannot run without it
+ * — it can, entirely from the composition's `config:` block. It is declared
+ * because the provider registers *asynchronously*: it reads the settings
+ * document first, so a plain `ctx.get('settings')` during `apply` can find
+ * nothing and the namespace silently never registers. Observed exactly that in
+ * production (`/rtk` reported "settings service unavailable" while a sibling
+ * `ctx.get('spillStore')` succeeded). Declaring it makes Cordis park this
+ * plugin until the provider appears, then activate it.
+ *
+ * `commands` and `systemPrompt` stay optional `ctx.get` lookups: they are
+ * registered early enough to be present, and a composition without them should
+ * still get the optimization.
+ */
+export const inject = ['tools', 'settings']
+
+export { Config }
+
+/** Tools whose `command` argument can be rewritten. */
+const REWRITABLE_TOOLS = new Set(['bash', 'pwsh'])
+
+/** Path of the rtk history database this plugin scopes rewritten commands to. */
+function rtkHistoryDbPath(): string {
+  return join(tmpdir(), 'dsh-rtk', 'history.db')
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : undefined
+}
+
+/**
+ * Appended once per session when rtk cannot be found.
+ *
+ * A missing binary is the only failure that silently costs the user the whole
+ * feature, so it is worth one short line — but only one, and only for a
+ * session that has not been told yet.
+ */
+const MISSING_RTK_NOTICE = '[rtk] rtk not found; rewriting is off — /rtk verify shows install options'
+
+/** The guidance injected while lossy read compaction is active. */
+const SOURCE_FILTER_TROUBLESHOOTING_NOTE =
+  'RTK note: if a file edit repeatedly fails because the old text does not match, read compaction may have altered the copy you are editing against. Ask the user to turn off `readCompaction` in the rtk settings, re-read the file, apply the edit, then turn it back on.'
+
+/** Whether lossy `read` compaction is enabled together with its safeguards. */
+function needsSourceFilterNote(config: RtkConfig): boolean {
+  const compaction = config.outputCompaction
+  return (
+    config.enabled &&
+    compaction.enabled &&
+    compaction.readCompaction.enabled &&
+    compaction.sourceCodeFilteringEnabled &&
+    compaction.sourceCodeFiltering !== 'none' &&
+    (compaction.smartTruncate.enabled || compaction.truncate.enabled)
+  )
+}
+
+/**
+ * Register RTK command rewriting and tool-output compaction.
+ *
+ * Both halves hang off the tool pipeline rather than wrapping a tool:
+ *
+ * - **Rewriting** rides `tools/execute`. The harness deliberately keeps
+ *   `tools/pre-execute` from mutating arguments (they are logged and presented
+ *   before dispatch), so the around-dispatch stage is the only seam where the
+ *   command that actually runs can differ from the one that was recorded. The
+ *   replacement is scoped to the call: the original arguments are restored as
+ *   soon as dispatch returns, so later pipeline stages and the session log see
+ *   what the model asked for.
+ * - **Compaction** rides `tools/post-execute`, which is the stage that may
+ *   replace result content.
+ *
+ * @param ctx - the agent-scoped context this row was mounted into.
+ * @param rawConfig - the row's `config:` block, already schema-validated.
+ */
+export function apply(ctx: Context, rawConfig: RtkConfig): void {
+  /**
+   * Whether the harness bounds oversized results itself.
+   *
+   * `dsh-spill-policy` writes a full output to disk and keeps a head/tail
+   * preview inline, so it truncates *recoverably*. This plugin's own hard
+   * truncation is lossy, and it runs first: at 12 000 characters it fires far
+   * below spill's threshold (50 000 by default), so spill never sees a large
+   * result at all and the reader loses the spill file that would have let them
+   * read the rest. When spill is mounted this plugin steps aside; when it is
+   * not, the truncation stays as the only bound on a runaway command.
+   */
+  const spillHandlesLargeOutput = ctx.get('spillStore') !== undefined
+
+  /**
+   * Apply the spill coordination to a freshly resolved configuration.
+   *
+   * Gated on an explicit switch rather than on "did the row set truncate?":
+   * the loader hands this function a schema-resolved config where every field
+   * already carries its default, so an absent key is indistinguishable from an
+   * explicit one. `deferToHarnessSpill: false` is how a row keeps its own
+   * bound regardless.
+   */
+  function coordinate(next: RtkConfig): RtkConfig {
+    if (spillHandlesLargeOutput && next.outputCompaction.deferToHarnessSpill) {
+      next.outputCompaction.truncate.enabled = false
+    }
+    return next
+  }
+
+  let config = coordinate(normalizeConfig(rawConfig))
+  let runtimeStatus: RtkRuntimeStatus = { rtkAvailable: false }
+  const metrics = createMetricsTracker()
+  /** Rewrite decisions awaiting their result, keyed by call id, for `suggest` mode. */
+  const pendingSuggestions = new Map<string, string>()
+  /** Call ids whose result should carry the one-time "rtk is missing" notice. */
+  const missingRtkCalls = new Set<string>()
+  /** Sessions already told that rtk is absent, so the notice is emitted once each. */
+  const notifiedAgents = new Set<string>()
+
+  // The settings namespace is process-global, so only the first instance of
+  // this plugin can own it. A host-plane row and a preset row both mounted, or
+  // two presets mounting the same row, would otherwise fail the second mount
+  // outright — a configuration convenience must never be the reason a whole
+  // preset refuses to activate. The loser follows the winner through the
+  // settings event instead.
+  const settings = ctx.get('settings') as SettingsProvider | undefined
+  let ownedScope: SettingsScope<unknown> | undefined
+  // Surfaced by `/rtk show`. A silently swallowed registration failure hides
+  // the only runtime-editable configuration path this plugin has, and the
+  // failure mode (settings edits simply do nothing) is invisible otherwise.
+  let settingsNote: string
+  if (settings === undefined) {
+    settingsNote = 'settings service unavailable — configuration comes from the composition only'
+  } else {
+    try {
+      const scope = settings.register('dsh-rtk', Config, { base: rawConfig })
+      ownedScope = scope as unknown as SettingsScope<unknown>
+      config = coordinate(normalizeConfig(scope.get()))
+      scope.watch((next) => {
+        config = coordinate(normalizeConfig(next))
+        applySourceFilterNote()
+      })
+      settingsNote = 'the `dsh-rtk` namespace in the harness settings document'
+    } catch (error) {
+      settingsNote = `settings namespace unavailable (${error instanceof Error ? error.message : String(error)}) — configuration comes from the composition only`
+      const existing = settings.get('dsh-rtk')
+      if (existing !== undefined) config = coordinate(normalizeConfig(existing))
+      ctx.on('settings/updated', (ns: string, next: unknown) => {
+        if (ns !== 'dsh-rtk') return
+        config = coordinate(normalizeConfig(next))
+        applySourceFilterNote()
+      })
+    }
+  }
+
+  let disposeNote: (() => void) | undefined
+  const systemPrompt = ctx.get('systemPrompt') as SystemPrompt | undefined
+  function applySourceFilterNote(): void {
+    if (systemPrompt === undefined) return
+    if (needsSourceFilterNote(config)) {
+      if (disposeNote !== undefined) return
+      disposeNote = systemPrompt.section({ name: 'rtk:read-compaction', order: 1010, text: SOURCE_FILTER_TROUBLESHOOTING_NOTE })
+      return
+    }
+    disposeNote?.()
+    disposeNote = undefined
+  }
+  applySourceFilterNote()
+  ctx.effect(() => () => {
+    disposeNote?.()
+    disposeNote = undefined
+  }, 'dsh-rtk.prompt-note')
+
+  async function refreshRuntimeStatus(): Promise<RtkRuntimeStatus> {
+    const resolution = await resolveRtkExecutable({ configured: config.rtkExecutable })
+    const probe = await runExecutable(resolution.command, ['--version'], { timeoutMs: 5000 })
+    const base = {
+      rtkExecutableCommand: resolution.command,
+      ...(resolution.resolvedPath === undefined ? {} : { rtkExecutablePath: resolution.resolvedPath }),
+      rtkExecutableResolver: resolution.resolver,
+      ...(resolution.warning === undefined ? {} : { rtkExecutableResolutionWarning: resolution.warning }),
+      lastCheckedAt: Date.now(),
+    }
+    runtimeStatus =
+      probe.code === 0
+        ? { rtkAvailable: true, ...base }
+        : {
+            rtkAvailable: false,
+            ...base,
+            lastError: (probe.stderr || probe.stdout).replace(/\s+/g, ' ').trim() || `exit ${probe.code}`,
+          }
+    return runtimeStatus
+  }
+
+  async function ensureRuntimeStatusFresh(): Promise<void> {
+    if (!shouldRequireRtkAvailability(config)) return
+    if (!isStatusStale(runtimeStatus, Date.now())) return
+    try {
+      await refreshRuntimeStatus()
+    } catch (error) {
+      runtimeStatus = {
+        rtkAvailable: false,
+        lastCheckedAt: Date.now(),
+        lastError: error instanceof Error ? error.message : String(error),
+      }
+    }
+  }
+
+  // ── command rewriting ────────────────────────────────────────────────────
+
+  ctx.on('tools/execute', async (exec: ToolDispatchExecution, next: () => Promise<ToolExecutionResult>) => {
+    if (!config.enabled) return next()
+    if (config.mode !== 'rewrite') return next()
+    if (!REWRITABLE_TOOLS.has(exec.name)) return next()
+
+    const args = asRecord(exec.arguments)
+    if (args === undefined || typeof args.command !== 'string') return next()
+
+    await ensureRuntimeStatusFresh()
+    if (shouldSkipRewrite(config, runtimeStatus)) {
+      // The guard is standing the rewrite down because rtk is unavailable. Flag
+      // this result so post-execute can say so once per session.
+      if (config.notifyWhenRtkMissing) {
+        if (missingRtkCalls.size > 256) missingRtkCalls.clear()
+        missingRtkCalls.add(exec.callId)
+      }
+      return next()
+    }
+
+    const decision = await resolveRtkRewrite(args.command, {
+      runner: runExecutable,
+      executable: runtimeStatus.rtkExecutableCommand ?? config.rtkExecutable,
+      timeoutMs: config.rewriteTimeoutMs,
+      signal: exec.signal,
+    })
+    if (!decision.changed) return next()
+
+    // `pwsh` is a rewrite target too, and PowerShell has no `export`.
+    const shell: ShellKind = exec.name === 'pwsh' ? 'powershell' : 'posix'
+    const command = applyRtkHistoryScope(decision.rewrittenCommand, rtkHistoryDbPath(), process.env.RTK_DB_PATH, shell)
+    if (config.showRewriteNotifications) {
+      // A cancelled call can be finalized on the `final-result` path, which
+      // bypasses post-execute and would leave its entry behind. The map is
+      // bounded so a notification nobody reads cannot grow without limit.
+      if (pendingSuggestions.size > 256) pendingSuggestions.clear()
+      pendingSuggestions.set(exec.callId, `[rtk] rewrote: ${decision.originalCommand} -> ${decision.rewrittenCommand}`)
+    }
+
+    // `arguments` is declared readonly, but the around-dispatch stage is the
+    // one place the registry re-reads it before invoking the body. Restoring it
+    // in `finally` keeps every later stage — post-execute, content
+    // finalization, and the observation in `tools/result` — looking at the call
+    // the model actually made.
+    const mutable = exec as unknown as { arguments: unknown }
+    mutable.arguments = { ...args, command }
+    try {
+      return await next()
+    } catch (error) {
+      pendingSuggestions.delete(exec.callId)
+      throw error
+    } finally {
+      mutable.arguments = args
+    }
+  })
+
+  // ── suggest mode ─────────────────────────────────────────────────────────
+
+  ctx.on('tools/execute', async (exec: ToolDispatchExecution, next: () => Promise<ToolExecutionResult>) => {
+    if (!config.enabled || config.mode !== 'suggest') return next()
+    if (!REWRITABLE_TOOLS.has(exec.name)) return next()
+
+    const args = asRecord(exec.arguments)
+    if (args === undefined || typeof args.command !== 'string') return next()
+
+    await ensureRuntimeStatusFresh()
+    if (shouldSkipRewrite(config, runtimeStatus)) {
+      // The guard is standing the rewrite down because rtk is unavailable. Flag
+      // this result so post-execute can say so once per session.
+      if (config.notifyWhenRtkMissing) {
+        if (missingRtkCalls.size > 256) missingRtkCalls.clear()
+        missingRtkCalls.add(exec.callId)
+      }
+      return next()
+    }
+
+    const decision = await resolveRtkRewrite(args.command, {
+      runner: runExecutable,
+      executable: runtimeStatus.rtkExecutableCommand ?? config.rtkExecutable,
+      timeoutMs: config.rewriteTimeoutMs,
+      signal: exec.signal,
+    })
+    if (decision.changed) {
+      if (pendingSuggestions.size > 256) pendingSuggestions.clear()
+      pendingSuggestions.set(exec.callId, `[rtk] suggestion: ${decision.rewrittenCommand}`)
+    }
+    try {
+      return await next()
+    } catch (error) {
+      pendingSuggestions.delete(exec.callId)
+      throw error
+    }
+  })
+
+  // ── output compaction ────────────────────────────────────────────────────
+
+  ctx.on('tools/post-execute', async (exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>) => {
+    const decision = await next()
+    let notice = pendingSuggestions.get(exec.callId)
+    pendingSuggestions.delete(exec.callId)
+
+    if (missingRtkCalls.delete(exec.callId) && config.notifyWhenRtkMissing) {
+      const agentKey = exec.agent?.id
+      if (agentKey !== undefined && !notifiedAgents.has(agentKey)) {
+        if (notifiedAgents.size > 256) notifiedAgents.clear()
+        notifiedAgents.add(agentKey)
+        notice = MISSING_RTK_NOTICE
+      }
+    }
+
+    if (decision.kind !== 'accept') return decision
+    if (!config.enabled) return decision
+
+    const source: readonly ContentBlock[] = decision.content ?? result.content
+    if (source.length === 0) return decision
+
+    let content: readonly ContentBlock[] = source
+    try {
+      const outcome = compactToolResult({ toolName: exec.name, args: exec.arguments, content: source }, config)
+      if (outcome.changed && outcome.content !== undefined) {
+        content = outcome.content as ContentBlock[]
+        if (outcome.metadata !== undefined && config.outputCompaction.trackSavings) {
+          metrics.track(
+            source.map((block) => (block as { text?: string }).text ?? '').join('\n'),
+            content.map((block) => (block as { text?: string }).text ?? '').join('\n'),
+            exec.name,
+            outcome.techniques,
+          )
+        }
+      }
+    } catch {
+      // Compaction is an optimization; a bug in it must not break the tool call.
+      return notice === undefined ? decision : { kind: 'accept', content: appendNotice(source, notice) }
+    }
+
+    // A sibling listener may have attached contexts for the next request.
+    // Rebuilding the decision without them would drop them silently, and the
+    // shipped search tool does exactly that when a result was capped.
+    const contexts = decision.additionalContexts
+    const rebuild = (blocks: ContentBlock[]): PostToolDecision => ({
+      kind: 'accept',
+      content: blocks,
+      ...(contexts === undefined ? {} : { additionalContexts: contexts }),
+    })
+
+    if (notice === undefined) {
+      return content === source ? decision : rebuild([...content])
+    }
+    return rebuild(appendNotice(content, notice))
+  })
+
+  // ── the /rtk command ─────────────────────────────────────────────────────
+
+  const commands = ctx.get('commands') as CommandRuntime | undefined
+  if (commands !== undefined) {
+    const command = createRtkCommand({
+      getConfig: () => config,
+      resetConfig: async () => {
+        if (ownedScope === undefined) return
+        await ownedScope.replace({})
+        config = coordinate(normalizeConfig(settings?.get('dsh-rtk')))
+      },
+      getRuntimeStatus: () => runtimeStatus,
+      refreshRuntimeStatus,
+      getMetrics: () => metrics.summary(),
+      clearMetrics: () => metrics.clear(),
+      configLocation: () => settingsNote,
+    })
+    ctx.effect(() => commands.register(command), 'dsh-rtk.command')
+  }
+}
+
+/**
+ * Insert a one-line notice into a result, ahead of any trailing status markers.
+ *
+ * The markers must stay last. The harness parses the final line for the exit
+ * status — the model is told to check `[exit code: N]` on every call, and the
+ * Web UI derives its exit-status pill from the same line. Appending a notice
+ * after them would break both silently, which is exactly what an earlier
+ * version of this function did.
+ */
+function appendNotice(content: readonly ContentBlock[], notice: string): ContentBlock[] {
+  const blocks: ContentBlock[] = [...content]
+  for (let index = blocks.length - 1; index >= 0; index -= 1) {
+    const block = blocks[index]
+    if (block === undefined || block.type !== 'text') continue
+
+    const parts = parseBashResult(block.text)
+    if (parts.empty || parts.markers.length === 0) {
+      blocks[index] = { type: 'text', text: `${block.text}\n${notice}` }
+      return blocks
+    }
+
+    const stdout = parts.stdout.length > 0 ? `${parts.stdout}\n${notice}` : notice
+    blocks[index] = { type: 'text', text: renderBashResult({ ...parts, stdout }) }
+    return blocks
+  }
+  return [...blocks, { type: 'text', text: notice }]
+}
+
+export { READ_COMPACTION_BANNER_PREFIX }

package/src/metrics.ts

@@ -0,0 +1,84 @@
+/** Per-tool savings accumulators for the current session. */
+export interface ToolSavings {
+  calls: number
+  originalChars: number
+  compactedChars: number
+}
+
+/** One session's compaction savings. */
+export interface MetricsSummary {
+  calls: number
+  originalChars: number
+  compactedChars: number
+  savedChars: number
+  savedPercent: number
+  byTool: Record<string, ToolSavings>
+  /** How often each technique fired, across all calls. */
+  byTechnique: Record<string, number>
+}
+
+/** Accumulates compaction savings; one instance per plugin application. */
+export interface MetricsTracker {
+  /** Record one compacted result. A no-op result must not be passed here. */
+  track(originalText: string, compactedText: string, tool: string, techniques: readonly string[]): void
+  /** Current totals, recomputed on each call so callers cannot mutate them. */
+  summary(): MetricsSummary
+  /** Drop all recorded savings. */
+  clear(): void
+}
+
+function emptyTotals(): ToolSavings {
+  return { calls: 0, originalChars: 0, compactedChars: 0 }
+}
+
+/**
+ * Build the session metrics accumulator.
+ *
+ * Savings are approximate by construction — character counts stand in for
+ * tokens — but they are measured on exactly the strings that were swapped, so
+ * the ratio is honest even when the absolute number is not.
+ */
+export function createMetricsTracker(): MetricsTracker {
+  let calls = 0
+  let originalChars = 0
+  let compactedChars = 0
+  const byTool = new Map<string, ToolSavings>()
+  const byTechnique = new Map<string, number>()
+
+  return {
+    track(originalText, compactedText, tool, techniques) {
+      calls += 1
+      originalChars += originalText.length
+      compactedChars += compactedText.length
+
+      const totals = byTool.get(tool) ?? emptyTotals()
+      totals.calls += 1
+      totals.originalChars += originalText.length
+      totals.compactedChars += compactedText.length
+      byTool.set(tool, totals)
+
+      for (const technique of techniques) byTechnique.set(technique, (byTechnique.get(technique) ?? 0) + 1)
+    },
+
+    summary() {
+      const savedChars = Math.max(0, originalChars - compactedChars)
+      return {
+        calls,
+        originalChars,
+        compactedChars,
+        savedChars,
+        savedPercent: originalChars === 0 ? 0 : Math.round((savedChars / originalChars) * 1000) / 10,
+        byTool: Object.fromEntries(byTool),
+        byTechnique: Object.fromEntries(byTechnique),
+      }
+    },
+
+    clear() {
+      calls = 0
+      originalChars = 0
+      compactedChars = 0
+      byTool.clear()
+      byTechnique.clear()
+    },
+  }
+}

package/src/rtk-executable.ts

@@ -0,0 +1,117 @@
+import { execFile } from 'node:child_process'
+
+/** One settled `rtk` invocation. */
+export interface RtkRunResult {
+  code: number
+  stdout: string
+  stderr: string
+}
+
+/** How an rtk executable path was discovered. */
+export type RtkResolverName = 'where' | 'which' | 'configured'
+
+/** The executable this plugin will use, and how sure it is. */
+export interface RtkExecutableResolution {
+  command: string
+  resolvedPath?: string
+  resolver: RtkResolverName
+  warning?: string
+}
+
+/** Everything the resolver needs; all fields have production defaults. */
+export interface ResolveRtkExecutableOptions {
+  /** Configured executable name or path. */
+  configured: string
+  /** Command used to look the name up on PATH. */
+  resolverCommand?: string
+  timeoutMs?: number
+  platform?: NodeJS.Platform
+}
+
+/** Resolver executable name for a platform. */
+export function resolverNameFor(platform: NodeJS.Platform): 'where' | 'which' {
+  return platform === 'win32' ? 'where' : 'which'
+}
+
+/**
+ * Invoke one executable and settle with its output.
+ *
+ * A missing binary or a non-zero exit resolves rather than rejects: every
+ * caller here treats "rtk said no" as an ordinary outcome, and rejecting would
+ * make each call site wrap the same try/catch. Arguments are passed as an
+ * array, so no command string is ever handed to a shell.
+ */
+export function runExecutable(
+  command: string,
+  args: readonly string[],
+  options: { timeoutMs?: number; signal?: AbortSignal } = {},
+): Promise<RtkRunResult> {
+  return new Promise((resolve) => {
+    execFile(
+      command,
+      [...args],
+      {
+        timeout: options.timeoutMs ?? 3000,
+        maxBuffer: 4 * 1024 * 1024,
+        windowsHide: true,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+      },
+      (error, stdout, stderr) => {
+        if (error === null) {
+          resolve({ code: 0, stdout, stderr })
+          return
+        }
+        const code = typeof (error as { code?: unknown }).code === 'number' ? (error as { code: number }).code : 1
+        resolve({ code, stdout: stdout ?? '', stderr: stderr ?? '' })
+      },
+    )
+  })
+}
+
+/** First non-empty line of resolver output, with surrounding quotes removed. */
+export function parseExecutablePath(stdout: string): string | undefined {
+  for (const line of stdout.split(/\r?\n/)) {
+    let candidate = line.trim()
+    if (candidate.length >= 2) {
+      const first = candidate[0]
+      const last = candidate[candidate.length - 1]
+      if ((first === '"' && last === '"') || (first === "'" && last === "'")) candidate = candidate.slice(1, -1)
+    }
+    if (candidate) return candidate
+  }
+  return undefined
+}
+
+/**
+ * Resolve the rtk executable, preferring the configured value.
+ *
+ * A configured value that is not a bare name is taken as an absolute path and
+ * used verbatim — the deployment said where rtk lives, so a PATH probe would
+ * only second-guess it. Bare names are looked up so `/rtk verify` can report a
+ * real path; a failed lookup is not fatal, because the name may still resolve
+ * when the command actually runs.
+ */
+export async function resolveRtkExecutable(options: ResolveRtkExecutableOptions): Promise<RtkExecutableResolution> {
+  const platform = options.platform ?? process.platform
+  const configured = options.configured.trim() || 'rtk'
+  const looksLikePath = configured.includes('/') || configured.includes('\\')
+
+  if (looksLikePath) {
+    return { command: configured, resolvedPath: configured, resolver: 'configured' }
+  }
+
+  const resolver = options.resolverCommand ?? resolverNameFor(platform)
+  const result = await runExecutable(resolver, [configured], { timeoutMs: options.timeoutMs ?? 1000 })
+  const resolvedPath = parseExecutablePath(result.stdout)
+
+  if (result.code === 0 && resolvedPath !== undefined) {
+    return { command: resolvedPath, resolvedPath, resolver: resolver as RtkResolverName }
+  }
+
+  const detail = (result.stderr || result.stdout).replace(/\s+/g, ' ').trim()
+  return {
+    command: configured,
+    resolver: resolver as RtkResolverName,
+    warning: `could not resolve ${configured} via ${resolver}${detail ? `: ${detail}` : ''}`,
+  }
+}