dsh-ops 0.0.0-stage → 0.2.2

package/lib/handshake.js

@@ -0,0 +1,252 @@
+/**
+ * The MCP stdio client this plugin owns.
+ *
+ * It is the plugin's transport: `lib/tools.js` keeps one long-lived client
+ * connected to the FastCtx server for as long as the plugin is mounted, calls
+ * `tools/call` through it, and rebuilds the whole tool generation after a
+ * reconnect. The same client also serves the callers that need ground truth
+ * without a host — `dsh-ops status`, and the suite that pins the tool surface
+ * the plugin's prompt policy advertises.
+ *
+ * It speaks newline-delimited JSON-RPC 2.0 and implements only the four methods
+ * those callers use.
+ *
+ * @module dsh-ops/handshake
+ */
+
+import { spawn } from 'node:child_process'
+
+/** The MCP revision this client announces. */
+export const PROTOCOL_VERSION = '2025-06-18'
+
+/** Error raised when the server does not answer in time. */
+export class McpTimeoutError extends Error {
+  /**
+   * @param {string} method - the unanswered method.
+   * @param {number} timeoutMs - the deadline that expired.
+   */
+  constructor(method, timeoutMs) {
+    super(`MCP server did not answer ${method} within ${timeoutMs} ms`)
+    this.name = 'McpTimeoutError'
+    this.method = method
+  }
+}
+
+/** Error raised when the server answers with a JSON-RPC error. */
+export class McpServerError extends Error {
+  /**
+   * @param {string} method - the failing method.
+   * @param {{code?: number, message?: string}} error - the JSON-RPC error object.
+   */
+  constructor(method, error) {
+    super(`MCP ${method} failed: ${error?.message ?? JSON.stringify(error)}`)
+    this.name = 'McpServerError'
+    this.code = error?.code
+  }
+}
+
+/** One newline-delimited JSON-RPC client over a spawned server's stdio. */
+export class McpStdioClient {
+  /**
+   * @param {import('node:child_process').ChildProcess} child - the spawned server.
+   * @param {number} timeoutMs - the default per-request deadline.
+   */
+  constructor(child, timeoutMs) {
+    this.child = child
+    this.timeoutMs = timeoutMs
+    this.nextId = 1
+    /** @type {Map<number, {resolve: (value: unknown) => void, reject: (error: Error) => void, method: string}>} */
+    this.pending = new Map()
+    /** @type {string[]} */
+    this.stderrLines = []
+    this.buffer = ''
+    this.closed = false
+    /** How this connection ended, or undefined while it is live. */
+    this.exitInfo = undefined
+
+    /**
+     * Settles once this connection is over, however it ended: a clean exit, a
+     * crash, or a spawn failure. A long-lived owner watches it to notice a dead
+     * server between calls instead of discovering it on the next timeout.
+     * @type {Promise<{code: number|null, signal: string|null, error?: Error}>}
+     */
+    this.exited = new Promise((resolve) => { this.resolveExit = resolve })
+
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', (chunk) => this.#ingest(chunk))
+    child.stderr.setEncoding('utf8')
+    child.stderr.on('data', (chunk) => {
+      for (const line of String(chunk).split('\n')) if (line.trim() !== '') this.stderrLines.push(line)
+    })
+    // A write to a server that is already gone must surface as this request's
+    // rejection (below), not as an unhandled stream error that kills the host.
+    child.stdin.on('error', () => {})
+
+    const settleExit = (info) => {
+      if (this.exitInfo !== undefined) return
+      this.exitInfo = info
+      this.closed = true
+      const reason = info.error !== undefined
+        ? new Error(`MCP server could not be started: ${info.error.message}`)
+        : new Error(`MCP server exited (code ${info.code ?? 'null'}, signal ${info.signal ?? 'none'})`)
+      for (const entry of this.pending.values()) entry.reject(reason)
+      this.pending.clear()
+      this.resolveExit(info)
+    }
+    child.once('exit', (code, signal) => settleExit({ code, signal }))
+    child.once('error', (error) => settleExit({ code: null, signal: null, error }))
+  }
+
+  /**
+   * Spawn one server and return a connected client (the MCP handshake is not
+   * performed; call {@link McpStdioClient#initialize}).
+   * @param {object} options - spawn inputs.
+   * @param {string} options.file - the executable.
+   * @param {string[]} [options.args] - its arguments.
+   * @param {string} [options.cwd] - working directory.
+   * @param {NodeJS.ProcessEnv} [options.env] - environment.
+   * @param {number} [options.timeoutMs] - the default per-request deadline.
+   * @returns {McpStdioClient} the client.
+   */
+  static start({ file, args = [], cwd, env = process.env, timeoutMs = 60_000 }) {
+    const child = spawn(file, args, {
+      cwd,
+      env,
+      windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    return new McpStdioClient(child, timeoutMs)
+  }
+
+  /**
+   * Consume whatever arrived and settle every complete line.
+   * @param {string} chunk - decoded stdout.
+   * @returns {void}
+   */
+  #ingest(chunk) {
+    this.buffer += chunk
+    let index
+    while ((index = this.buffer.indexOf('\n')) >= 0) {
+      const line = this.buffer.slice(0, index).trim()
+      this.buffer = this.buffer.slice(index + 1)
+      if (line === '') continue
+      let message
+      try {
+        message = JSON.parse(line)
+      } catch {
+        // A non-JSON line on stdout is the server's problem, not a protocol
+        // message; recording it keeps the diagnosis attached to a failure.
+        this.stderrLines.push(`non-JSON stdout: ${line.slice(0, 400)}`)
+        continue
+      }
+      const entry = message.id === undefined ? undefined : this.pending.get(message.id)
+      if (entry === undefined) continue
+      if (message.error !== undefined) entry.reject(new McpServerError(entry.method, message.error))
+      else entry.resolve(message.result)
+    }
+  }
+
+  /**
+   * Send one request and await its result.
+   * @param {string} method - the JSON-RPC method.
+   * @param {Record<string, unknown>} [params] - its parameters.
+   * @param {object} [options] - per-request overrides.
+   * @param {number} [options.timeoutMs] - this request's deadline.
+   * @param {AbortSignal} [options.signal] - cancels this request when aborted.
+   * @returns {Promise<any>} the result.
+   */
+  request(method, params = {}, options = {}) {
+    const { timeoutMs = this.timeoutMs, signal } = options
+    if (this.closed) return Promise.reject(new Error(`MCP server is gone; cannot send ${method}`))
+    if (signal?.aborted === true) {
+      return Promise.reject(new Error(`MCP ${method} was canceled before it was sent`))
+    }
+    const id = this.nextId++
+    return new Promise((resolve, reject) => {
+      let timer
+      let settled = false
+      const finish = (settle, value) => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        signal?.removeEventListener('abort', onAbort)
+        this.pending.delete(id)
+        settle(value)
+      }
+      const onAbort = () => finish(reject, new Error(`MCP ${method} was canceled`))
+      timer = setTimeout(() => finish(reject, new McpTimeoutError(method, timeoutMs)), timeoutMs)
+      timer.unref?.()
+      signal?.addEventListener('abort', onAbort, { once: true })
+      this.pending.set(id, {
+        method,
+        resolve: (value) => finish(resolve, value),
+        reject: (error) => finish(reject, error),
+      })
+      this.child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`)
+    })
+  }
+
+  /**
+   * Send one notification (no reply is expected).
+   * @param {string} method - the JSON-RPC method.
+   * @param {Record<string, unknown>} [params] - its parameters.
+   * @returns {void}
+   */
+  notify(method, params = {}) {
+    if (this.closed) return
+    this.child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method, params })}\n`)
+  }
+
+  /**
+   * Perform the MCP handshake.
+   * @param {string} [clientName] - the name to announce.
+   * @returns {Promise<{protocolVersion: string, serverInfo: {name: string, version: string}, instructions?: string, capabilities: Record<string, unknown>}>} the server's answer.
+   */
+  async initialize(clientName = 'dsh-ops') {
+    const result = await this.request('initialize', {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: clientName, version: '0.1.0' },
+    })
+    this.notify('notifications/initialized', {})
+    return result
+  }
+
+  /**
+   * List the server's tools.
+   * @returns {Promise<{name: string, description?: string, inputSchema?: Record<string, unknown>, outputSchema?: Record<string, unknown>}[]>} the tools.
+   */
+  async listTools() {
+    const result = await this.request('tools/list', {})
+    return result?.tools ?? []
+  }
+
+  /**
+   * Call one tool and return its raw result.
+   * @param {string} toolName - the server's own tool name.
+   * @param {Record<string, unknown>} args - the arguments.
+   * @param {object} [options] - per-request overrides (deadline, cancellation).
+   * @returns {Promise<{content?: unknown[], isError?: boolean, structuredContent?: unknown}>} the result.
+   */
+  async callTool(toolName, args, options = {}) {
+    return this.request('tools/call', { name: toolName, arguments: args }, options)
+  }
+
+  /**
+   * Stop the server and wait for the process to settle.
+   *
+   * Idempotent, and safe to call on a connection that already ended: the
+   * process is only signalled while it is still alive.
+   * @returns {Promise<void>} resolves once the child is gone.
+   */
+  async close() {
+    if (this.closed) return
+    const exited = this.exited
+    this.child.stdin.end()
+    this.child.kill()
+    const guard = setTimeout(() => this.child.kill('SIGKILL'), 4_000)
+    guard.unref?.()
+    await exited
+    clearTimeout(guard)
+  }
+}

package/lib/index.js

@@ -0,0 +1,108 @@
+/** dsh-ops host half. Own registrations only; no @deepseek-ai value imports. */
+import { PACKAGE_ROOT, probeBinary, resolveBinary } from './binary.js'
+import { resolveConfig } from './config.js'
+import { SECTION_ORDERS, TOOLING_SECTION, hostShellRefusal, renderToolingPolicy } from './policy.js'
+import { resolveShells } from './shells.js'
+import { mountSessionBash } from './session-shells.js'
+import { FastCtxTools } from './tools.js'
+
+export const name = 'dsh-ops'
+function report(ctx, message, level = 'error') {
+  const logger = ctx?.logger
+  if (typeof logger?.[level] === 'function') logger[level](message)
+  else if (level === 'warn') console.warn(message)
+  else console.error(message)
+}
+function visibleTools(ctx, agent) {
+  try {
+    return (ctx.get('tools')?.schemas(agent) ?? []).map(schema => schema.name)
+      .filter(tool => typeof tool === 'string')
+  } catch { return [] }
+}
+function prepareRuntime(ctx, config) {
+  try {
+    const resolved = resolveBinary({ binaryPath: config.binaryPath, packageRoot: PACKAGE_ROOT })
+    const probe = probeBinary(resolved.file)
+    if (!probe.ok) throw new Error(`Unusable FastCtx at ${resolved.file}: ${probe.detail}`)
+    return { file: resolved.file, source: resolved.source, version: probe.version }
+  } catch (error) {
+    report(ctx, `dsh-ops: ${error.message}`)
+    if (config.required) throw error
+  }
+}
+
+/** Explicit host-shell denial is independent of whether ops commands exist. */
+function installHostShellDenial(ctx, config) {
+  const denied = new Set(config.deniedHostTools)
+  const lifts = new Map()
+  const hide = agent => {
+    if (lifts.has(agent) || !agent?.ctx) return
+    try {
+      const names = (ctx.get('tools').schemas(agent) ?? []).map(tool => tool.name).filter(name => denied.has(name))
+      if (names.length) lifts.set(agent, agent.ctx.tools.restrict({ deny: names }))
+    } catch (error) {
+      report(ctx, `dsh-ops: host shell visibility restriction unavailable: ${error.message}; calls remain denied.`, 'warn')
+    }
+  }
+  ctx.on('agent/created', ({ agent }) => hide(agent))
+  ctx.on('agent/disposed', ({ agent }) => { lifts.get(agent)?.(); lifts.delete(agent) })
+  for (const agent of ctx.get('agents')?.list?.() ?? []) hide(agent)
+  ctx.effect(() => () => { for (const lift of lifts.values()) lift(); lifts.clear() }, 'dsh-ops: host shell restrictions')
+  ctx.on('tools/pre-execute', (exec, next) => hostShellRefusal({ toolName: String(exec?.name ?? ''), denied }) ?? next())
+  if (typeof ctx.tools.guard === 'function') {
+    ctx.effect(() => ctx.tools.guard(exec => hostShellRefusal({ toolName: String(exec?.name ?? ''), denied })?.reason), 'dsh-ops: host shell guard')
+  }
+}
+
+async function mountServer(ctx, config, runtime) {
+  if (!runtime) return
+  const surface = new FastCtxTools({ ctx, config, runtime, report: (message, level) => report(ctx, message, level) })
+  ctx.effect(() => () => surface.stop(), 'dsh-ops: fastctx server')
+  ctx.on('agent/created', ({ agent }) => surface.attachAgent(agent))
+  ctx.on('agent/disposed', ({ agent }) => surface.detachAgent(agent))
+  ctx.on('session/event', (session, event) => {
+    if (event.type === 'sandbox/mode') surface.refreshAgents(session)
+  })
+  // Authority may mount after the tools service or be hot-reloaded. Losing it
+  // immediately retires every command layer; it never falls back to env state.
+  surface.authorityAvailable = false
+  ctx.inject(['sandboxPolicy'], authorityCtx => {
+    surface.authorityAvailable = true
+    surface.refreshAgents()
+    authorityCtx.effect(() => () => {
+      surface.authorityAvailable = false
+      surface.refreshAgents()
+    }, 'dsh-ops: permission authority')
+  })
+  for (const agent of ctx.get('agents')?.list?.() ?? []) surface.attachAgent(agent)
+  try {
+    const tools = await surface.start()
+    report(ctx, `dsh-ops: FastCtx ${runtime.version} ready; ${tools.length} file tools, session-authorized command layers.`, 'info')
+  } catch (error) {
+    report(ctx, `dsh-ops: FastCtx unavailable: ${error.message}`)
+    if (config.required) throw error
+    surface.retryLater()
+  }
+}
+
+export function apply(root, rawConfig) {
+  const config = resolveConfig(rawConfig)
+  const runtime = prepareRuntime(root, config)
+  const shells = resolveShells(config)
+  if (config.promptPolicy) root.inject(['systemPrompt'], ctx => {
+    ctx.effect(() => ctx.systemPrompt.section({
+      name: TOOLING_SECTION,
+      order: SECTION_ORDERS[TOOLING_SECTION],
+      interpolate: false,
+      text: context => renderToolingPolicy({
+        published: visibleTools(ctx, context.agent), pwsh7: shells.pwsh.available,
+        extraGuidance: config.extraGuidance,
+      }),
+    }), 'dsh-ops: repository tooling')
+  })
+  root.inject(['tools'], ctx => {
+    mountSessionBash(ctx, config, shells)
+    if (config.shellPolicy === 'deny-host-shell') installHostShellDenial(ctx, config)
+    return mountServer(ctx, config, runtime)
+  })
+}

package/lib/jobs.js

@@ -0,0 +1,42 @@
+/** Plugin-side projections over FastCtx's text protocol. Never adopt foreign IDs. */
+const ID = 'j-[a-z0-9]{6}'
+const ENTRY = new RegExp(`^(${ID}) (?:running \\d+(?:s|m\\d+s|h\\d+m)|exited -?\\d+|killed|interrupted)$`)
+
+export function startedJob(value) {
+  for (const block of value.content ?? []) {
+    if (block.type !== 'text') continue
+    const match = /(?:^|\n)\(Complete: job (j-[a-z0-9]{6}) started; log at [^\n]*\.\)\s*$/.exec(block.text)
+    if (match) return match[1]
+  }
+}
+
+/** Only touch the final server decoration, never arbitrary lines in command output. */
+export function cleanBackground(value, owned) {
+  const content = [...value.content]
+  const index = content.findLastIndex(block => block?.type === 'text')
+  if (index < 0) return value
+  const block = content[index]
+  const text = block.text
+  if (typeof text !== 'string') return value
+  const match = /(?:^|\n)\(Background: ([^\n]*)\.\)(?=\s*(?:\((?:Complete|Partial|Killed):[^\n]*\))?\s*$)/.exec(text)
+  if (!match) return value
+  const entries = match[1].split(', ')
+  if (!entries.every(entry => ENTRY.test(entry)) && !/^\d+ jobs? running$/.test(match[1])) return value
+  const kept = entries.filter(entry => {
+    const parsed = ENTRY.exec(entry)
+    return parsed && owned.has(parsed[1])
+  })
+  const replacement = kept.length ? `${match[0].startsWith('\n') ? '\n' : ''}(Background: ${kept.join(', ')}.)` : ''
+  content[index] = { ...block, text: text.slice(0, match.index) + replacement + text.slice(match.index + match[0].length) }
+  return { ...value, content }
+}
+
+/** Parse only the upstream job-list entry boundaries, not arbitrary output text. */
+export function jobEntries(value) {
+  const text = value.content.filter(block => block?.type === 'text').map(block => block.text).join('\n')
+  const entries = []
+  const regex = /(?:^|\n\n)(j-[a-z0-9]{6})  (running|killed|exited -?\d+|interrupted); started ([^\n]*)\n  ([^\n]*)/g
+  for (const match of text.matchAll(regex)) entries.push({ id: match[1], status: match[2], text: match[0].trimStart() })
+  const next = /\(Partial:[^\n]*\boffset[=: ]+(\d+)/.exec(text)
+  return { entries, next: next ? Number(next[1]) : undefined, partial: /(?:^|\n)\(Partial:/.test(text) }
+}

package/lib/policy.js

@@ -0,0 +1,64 @@
+/** Model-facing routing, kept in one section. No shared registry mutation. */
+export const TOOLING_SECTION = 'dsh-ops:repository-tooling'
+// Legacy section name kept for consumers; the plugin no longer publishes it.
+export const HOST_SHELL_SECTION = 'dsh-ops:host-shell-policy'
+export const SECTION_ORDERS = Object.freeze({ [TOOLING_SECTION]: 3250 })
+export const TOOL_PREFIX = 'ops_'
+export const FILE_TOOLS = Object.freeze(['inspect_local_file', 'grep', 'glob', 'replace'])
+export const SHELL_TOOLS = Object.freeze(['run', 'run_background', 'job_output', 'job_list', 'job_kill'])
+// The plugin's second layer executes POSIX commands; pwsh7 uses the host tool.
+export const IN_PROCESS_TOOLS = Object.freeze(['bash'])
+export function publicToolName(rawName) { return `${TOOL_PREFIX}${rawName}` }
+export const BASH_TOOL = publicToolName('bash')
+
+/** Resolve the actual command capability, not the presence of a shell executable. */
+export function ladderLevels({ published, pwsh = false }) {
+  const names = new Set(published)
+  return {
+    fastctx: FILE_TOOLS.some(name => names.has(publicToolName(name))),
+    run: names.has(publicToolName('run')),
+    bash: names.has(BASH_TOOL),
+    pwsh: pwsh === true && names.has('pwsh'),
+  }
+}
+
+/** A single compact table; absent tools never get advertised. */
+export function renderToolingPolicy({ published, enableShellTools, mounted, levels, pwsh7 = false, extraGuidance = '' }) {
+  const names = new Set(published ?? (mounted || levels?.fastctx
+    ? [...FILE_TOOLS, ...(enableShellTools ? SHELL_TOOLS : []), ...(levels?.bash ? IN_PROCESS_TOOLS : [])].map(publicToolName) : []))
+  if (levels?.pwsh) names.add('pwsh')
+  if (!FILE_TOOLS.some(name => names.has(publicToolName(name))) && !names.has(BASH_TOOL)) return ''
+  const lines = ['# Repository operations: tools → bash → PowerShell 7', '', '| Task | Tool |', '| --- | --- |']
+  const row = (raw, task) => {
+    if (names.has(publicToolName(raw))) lines.push(`| ${task} | ${publicToolName(raw)} |`)
+  }
+  row('inspect_local_file', 'Text / multiple ranges / encoding / PDF text / hex')
+  lines.push('| Images | read_image (host) |')
+  row('grep', 'Search contents')
+  row('glob', 'Find paths')
+  row('replace', 'Batch replacement; use host edit for precise edits')
+  row('bash', 'General commands / builds / git / pipelines / scripts — preferred command executor')
+  if (names.has('pwsh')) lines.push(`| Windows-native cmdlets / registry / services only | pwsh (${pwsh7 || levels?.pwsh ? 'bundled PowerShell 7 via host' : 'host PowerShell'}) |`)
+  row('run', 'Bounded bash command result (full access only)')
+  if (names.has(publicToolName('run_background'))) {
+    lines.push(`| Background commands / owned jobs | ${SHELL_TOOLS.slice(1).map(publicToolName).join(', ')} |`)
+  }
+  lines.push('', '- Do not build shell command lines for file operations.',
+    '- On a tool error, correct the arguments and retry; do not switch to a shell workaround.')
+  if (names.has(BASH_TOOL)) lines.push('- Prefer bash for command execution. Use PowerShell only when Windows-native functionality is necessary; fix bash errors in bash, do not switch shells or mix their syntax.')
+  if (names.has(publicToolName('run_background'))) lines.push('- Only operate on job IDs you started in this session.')
+  if (extraGuidance.trim()) lines.push('', extraGuidance.trim())
+  return lines.join('\n')
+}
+
+/** Legacy API: no second prompt section. */
+export function renderHostShellPolicy() { return '' }
+
+/** Explicit deny policy applies even without an ops command capability. */
+export function hostShellEnforcement({ shellPolicy }) {
+  return { hide: shellPolicy === 'deny-host-shell', reason: undefined }
+}
+export function hostShellRefusal({ toolName, denied }) {
+  if (!denied.has(toolName)) return undefined
+  return { kind: 'deny', reason: `Host tool ${toolName} is disabled by dsh-ops shellPolicy. Use an available file tool for file operations; otherwise request an operator policy change.` }
+}

package/lib/presentation.js

@@ -0,0 +1,63 @@
+/** Compact presentation only; arguments are forwarded unchanged. */
+const DESCRIPTIONS = {
+  inspect_local_file: 'Read text ranges (prefer files[] batches, up to 32), known encodings, PDF text or hex. Images: use host read_image.',
+  grep: 'Search contents with ripgrep; glob[] supports batched filters and ! exclusions. Use summary/count/files_with_matches to reduce output.',
+  glob: 'Find paths. Prefer pattern[] batches with ! exclusions; choose paths or details output.',
+  replace: 'Mechanical replacement across files; use host edit for precise changes. Check dry-run results before applying.',
+  run: 'Run a bash command (not PowerShell), returning bounded output and exit status.',
+  run_background: 'Start a bash job; keep the returned job ID for output and termination in this session.',
+  job_output: 'Read output of a job started in this session; use after_seq for explicit continuation.',
+  job_list: 'List only jobs started in this session and connection; status and pagination apply to owned jobs.',
+  job_kill: 'Terminate the process tree of a job started in this session.',
+}
+const FIELDS = {
+  file_path: 'Absolute local path, not a URI; exclusive with files.',
+  path: 'Absolute local path, not a URI; omit for connection directory where optional. Reuse escaped filenames verbatim.',
+  fallback_encoding: 'Directory fallback for undecodable files; never overrides BOM or valid UTF-8.',
+  filter_mode: 'ignore respects .ignore only; all disables filtering. Both include hidden/.git files; neither reads Git ignores.',
+  output_mode: 'Select the output shape; grep defaults to files_with_matches, glob to paths. Grep summary ignores paging.',
+  head_limit: 'Maximum output entries; 0 removes this limit, not the token budget.',
+  timeout_ms: 'Command process-tree timeout in milliseconds, max 240000.',
+  cwd: 'Absolute working directory; omit for the FastCtx connection directory (not the calling session).',
+  encoding: 'Source encoding label (e.g. gbk); omit for detection. Output is UTF-8.',
+  files: 'Prefer batches: 1-32 text ranges, in order; exclusive with file_path and top-level offset/encoding/pages/pdf_mode/view. Top-level limit is a default.',
+  offset: 'Continuation offset; use the returned paging marker.',
+  limit: 'Maximum results/lines; read batch entries override the top-level default.',
+  pages: 'PDF page range, e.g. 1-5; max 20 pages. Required for text PDFs over 10 pages.',
+  pdf_mode: 'PDF text layer only; rendered images are unsupported.',
+  view: 'auto selects text/PDF; hex inspects raw bytes of any file.',
+  glob: 'Prefer glob[] batches; ! excludes paths.',
+  context: 'Content mode: lines before and after each match.',
+  job_id: 'ID returned by your own run_background in this session.',
+  wait_ms: 'Wait milliseconds, max 240000; default 30000.',
+  after_seq: 'Output sequence cursor; omit to use this connection\'s cursor.',
+  command: 'Bash command, not PowerShell syntax.',
+  login_shell: 'Use bash login shell; default true.',
+}
+function shorten(schema, field, tool) {
+  if (Array.isArray(schema)) return schema.map(value => shorten(value, field, tool))
+  if (!schema || typeof schema !== 'object') return schema
+  const result = {}
+  for (const [key, value] of Object.entries(schema)) {
+    if (key === 'description') {
+      result[key] = field === 'pattern'
+        ? (tool === 'grep' || tool === 'replace' ? 'Rust regex; escape literal braces. One pattern per call.' : 'Prefer pattern[] batches; ! excludes paths.')
+        : field === 'offset' ? (tool === 'inspect_local_file' ? 'Start at this 1-based line; use for continuation.' : 'Skip this many results (0-based); use for continuation.')
+        : field === 'encoding' && tool === 'grep' ? 'Single-file encoding label (e.g. gbk); directories use fallback_encoding.'
+        : FIELDS[field] ?? String(value).replace(/\s+/g, ' ').trim()
+    } else if (key === 'properties') {
+      result[key] = Object.fromEntries(Object.entries(value).map(([name, child]) => [name, shorten(child, name, tool)]))
+    } else result[key] = shorten(value, field, tool)
+  }
+  return result
+}
+export function projectTool(tool) {
+  const inputSchema = shorten(tool.inputSchema ?? { type: 'object', properties: {} }, '', tool.name)
+  if (tool.name === 'grep') {
+    // Asymmetric context remains accepted by FastCtx but is not advertised.
+    delete inputSchema.properties?.before_context
+    delete inputSchema.properties?.after_context
+  }
+  if (tool.name === 'inspect_local_file' && inputSchema.properties?.pdf_mode) inputSchema.properties.pdf_mode.enum = ['text']
+  return { ...tool, description: DESCRIPTIONS[tool.name] ?? tool.description ?? '', inputSchema }
+}

package/lib/profile-install.js

@@ -0,0 +1,61 @@
+/** Profile operations delegate to the official CLI instead of reimplementing its locks and rollback. */
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { createRequire } from 'node:module'
+import { spawnSync } from 'node:child_process'
+import { PACKAGE_ROOT, dshHome } from './binary.js'
+
+export function profileCommand(operation, { profile, dshCli, dryRun = false }) {
+  if (process.platform !== 'win32' || process.arch !== 'x64') throw new Error('Only Windows x64 is supported.')
+  const aliases = { desktop: 'desktop', web: 'web', tui: 'dsh-tui', 'dsh-tui': 'dsh-tui' }
+  if (!Object.hasOwn(aliases, profile ?? '')) throw new Error('Explicit --profile desktop|web|tui is required (tui maps to dsh-tui).')
+  const target = aliases[profile]
+  const directory = path.join(dshHome(), 'profiles', target)
+  if (!fs.existsSync(path.join(directory, 'package.json'))) throw new Error(`Initialize the target DSH application/profile first: ${directory}`)
+  const version = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8')).version
+  if (operation === 'status') {
+    const manifest = JSON.parse(fs.readFileSync(path.join(directory, 'package.json'), 'utf8'))
+    console.log(JSON.stringify({ profile: target, directory, dependency: manifest.dependencies?.['dsh-ops'] ?? null, enabled: (manifest.dsh?.profile?.bundles ?? []).includes('dsh-ops') }, null, 2))
+    return 0
+  }
+  const args = ['plugin', '--profile', target, operation === 'install' ? 'add' : 'remove', operation === 'install' ? `dsh-ops@${version}` : 'dsh-ops']
+  let command = dshCli ?? process.env.DSH_OPS_DSH_CLI
+  let prefix = []
+  if (!command && target === 'desktop') {
+    const local = process.env.LOCALAPPDATA ?? path.join(os.homedir(), 'AppData/Local')
+    command = [path.join(local, 'Programs/DeepSeek Harness/resources/runtime/cli/bin/dsh.cmd')].find(file => fs.existsSync(file))
+    if (!command) throw new Error('Desktop requires its own CLI. Pass --dsh-cli <installation>/resources/runtime/cli/bin/dsh.cmd; ordinary dsh cannot manage desktop.')
+  }
+  if (!command) {
+    const globalNpm = process.env.APPDATA ? path.join(process.env.APPDATA, 'npm/node_modules/_anchor.json') : undefined
+    for (const anchor of [path.join(directory, 'package.json'), path.join(dshHome(), 'package.json'), globalNpm].filter(Boolean)) {
+      try {
+        const require = createRequire(anchor)
+        const file = require.resolve('@deepseek-ai/dsh/package.json')
+        const manifest = JSON.parse(fs.readFileSync(file, 'utf8'))
+        const bin = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.dsh
+        if (bin) { command = process.execPath; prefix = [path.resolve(path.dirname(file), bin)]; break }
+      } catch {}
+    }
+    if (!command) {
+      const desktopCli = path.join(process.env.LOCALAPPDATA ?? path.join(os.homedir(), 'AppData/Local'), 'Programs/DeepSeek Harness/resources/runtime/cli/bin/dsh.cmd')
+      command = fs.existsSync(desktopCli) ? desktopCli : 'dsh.cmd'
+    }
+  }
+  console.log(`Target: ${target} (${directory})`)
+  console.log(`Official CLI: ${command}; ${args.join(' ')}`)
+  if (dryRun) return 0
+  let result
+  if (/\.cmd$/i.test(command)) {
+    // cmd wrappers are Windows-owned launchers; reject shell metacharacters in caller-supplied paths.
+    if (/["\r\n&|<>^%!]/.test(command)) throw new Error('Unsafe CLI path; use a path without cmd metacharacters.')
+    result = spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `""${command}" ${args.join(' ')}"`], { stdio: 'inherit', windowsHide: true })
+  } else result = spawnSync(command, [...prefix, ...args], { stdio: 'inherit', windowsHide: true })
+  if (result.error) throw result.error
+  if (result.status !== 0) return result.status ?? 1
+  console.log(operation === 'install'
+    ? 'Installed through the official profile manager. Reload/restart the target application if needed. Binaries are profile dependencies; no postinstall downloads.'
+    : 'Removed through the official profile manager, including its runtime dependency references. Package-manager shared caches are not deleted.')
+  return 0
+}