deepseek-coordination 0.1.0 → 0.1.2

package/src/plugin/takeover.js

@@ -0,0 +1,392 @@
+/**
+ * dsh-os takeover: route the built-in file and shell tools onto dsh-os verbs.
+ *
+ * WHY THIS IS A SEPARATE PLUGIN ROW
+ *
+ * `dsh_os` is a tool the model has to be *told* to use. In practice it never is: the built-in
+ * `read`/`write`/`edit`/`pwsh` tools are right there, they overlap almost completely, and nothing in
+ * the prompt prefers one over the other. The result is that the byte-level guarantees this project
+ * exists for are never exercised — the plugin is installed and imperceptible.
+ *
+ * This row removes the choice. When a user enables takeover in the settings panel, the built-in calls
+ * are intercepted and answered by the same machinery, so the guarantees apply whether or not the model
+ * cooperates.
+ *
+ * WHY `tools/execute` AND NOT A SHADOWING REGISTRATION
+ *
+ * `@deepseek-ai/dsh-tools` lets a scoped registration shadow a global tool, which looks like the
+ * obvious mechanism. It does not work here. The Web/desktop composition disables the host-side
+ * `tool-fs`/`tool-pwsh` rows and remounts them inside every agent *preset* (`dsh-web-app`'s patch),
+ * so the built-ins live in a scope layer that is NEARER than any global registration this plugin could
+ * make — the preset would shadow us, not the other way round.
+ *
+ * `tools/execute` (dsh-tools `dispatchScheduledExecution`) is the around-dispatch waterfall:
+ *
+ *     ctx.waterfall(carrier, "tools/execute", mutableExec, () => this.dispatchToolBody(mutableExec))
+ *
+ * A handler that returns `{ value }` without calling `next()` replaces the tool body's value. The
+ * value is then validated against the BUILT-IN tool's own `output.schema` and rendered by the BUILT-IN
+ * `output.render` (`normalizeDispatchResult` -> `createSuccessResult`), so the model-facing text, the
+ * diff cards and the presentation metadata stay exactly what they were: the only thing that changes is
+ * where the bytes came from.
+ *
+ * WHAT IS DELIBERATELY NOT TAKEN OVER
+ *
+ *   * `glob` and `grep` stay built-in. dsh-os has no content-search verb at all, and `file search`
+ *     matches names rather than contents, so forwarding them would silently lose results.
+ *   * `run_in_background` command calls stay built-in: the built-in result for a background call is a
+ *     job id from the harness job system, and dsh-os's `--background` starts an unrelated process with
+ *     a pid. Claiming otherwise would hand the model a handle it cannot collect.
+ *   * Relative paths are not intercepted. The built-in `read`/`write`/`edit` resolve against the
+ *     session's workspace root through `ctx.fs`; an interception that used the process working
+ *     directory instead would silently read a different file. Interception requires an absolute path.
+ *   * `sandbox_permissions` escalation is not honoured. The built-in body asks `ctx.approval` for a
+ *     wider sandbox before touching the file; a redirected call runs the verb directly, so the file
+ *     sandbox is not what bounds it — dsh-os's own protected-path check is. This is a real reduction
+ *     in defence and is documented in README.md rather than hidden.
+ *
+ * FALLBACK IS THE CONTRACT
+ *
+ * Every interception is wrapped: anything unexpected — a verb this build does not have, an encoding
+ * dsh-os refuses, a malformed path — calls `next()` and lets the built-in tool do the work. Takeover
+ * can therefore only ever change HOW a call is answered, never whether it is answered. A model that
+ * cannot see the difference is the point.
+ */
+
+import { randomBytes } from 'node:crypto'
+import { existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join } from 'node:path'
+
+import { invokeForResult, resolveInvocation } from './invoke.js'
+
+export const name = 'dsh-os-takeover'
+
+/** The interception needs the tool pipeline, and the switch lives in the settings service. */
+export const inject = ['tools', 'dsh-os-settings']
+
+/**
+ * Tools this row knows how to answer.
+ *
+ * The order is also the order the settings panel presents them in. Leaving a tool out is a supported
+ * configuration, not a degraded one: with `read` off, reads are the built-in implementation and writes
+ * still go through dsh-os.
+ */
+export const TAKEOVER_TOOLS = ['read', 'write', 'edit', 'pwsh']
+
+/** Defaults matching the "follow the built-in, preserve the target" policy chosen for this feature. */
+export const DEFAULT_CONFIG = {
+  read: true,
+  write: true,
+  edit: true,
+  pwsh: true,
+}
+
+// ---------------------------------------------------------------------------
+// target format detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the byte-level facts the built-in tools do not preserve.
+ *
+ * The built-in `write` always emits UTF-8 with no BOM and LF line endings. Rewriting a file that had a
+ * BOM or CRLF therefore produces a whole-file diff and can break a script that depended on the
+ * convention. Which of the two the target already had is only knowable from its bytes, so they are
+ * read here rather than guessed.
+ *
+ * A file that does not exist yields the built-in defaults, which is what makes a newly created file
+ * behave exactly as it did before takeover was enabled.
+ */
+export function readTargetFormat(path) {
+  let bytes
+  try {
+    bytes = readFileSync(path)
+  } catch {
+    return { exists: false, bom: false, eol: 'lf' }
+  }
+  const bom = bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf
+  let crlf = 0
+  let lf = 0
+  for (let index = 0; index < bytes.length; index += 1) {
+    if (bytes[index] !== 0x0a) continue
+    if (index > 0 && bytes[index - 1] === 0x0d) crlf += 1
+    else lf += 1
+  }
+  // A file with no line ending at all is treated as LF, which is the built-in default and therefore
+  // changes nothing about how it will be written.
+  const eol = crlf > lf ? 'crlf' : 'lf'
+  return { exists: true, bom, eol }
+}
+
+/** Decode a text file's bytes the way the built-in `read` does: BOM stripped, CRLF normalised to LF. */
+export function decodeTextFile(bytes) {
+  const hasBom = bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf
+  const body = hasBom ? bytes.subarray(3) : bytes
+  return body.toString('utf8').replace(/\r\n/g, '\n')
+}
+
+/** Encode text back into a target's convention, so the write preserves what was already there. */
+export function encodeTextForTarget(text, format) {
+  const body = format.eol === 'crlf' ? text.replace(/\r\n/g, '\n').replace(/\n/g, '\r\n') : text.replace(/\r\n/g, '\n')
+  const payload = Buffer.from(body, 'utf8')
+  if (!format.bom) return payload
+  return Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), payload])
+}
+
+/**
+ * Replace a file's bytes atomically.
+ *
+ * Same-directory temporary file then `rename`, which is the same shape dsh-os's own `Write-Atomic`
+ * uses. A cross-volume rename would not be atomic, and this is never one: the temporary file is a
+ * sibling of its target by construction.
+ *
+ * The temporary name is random rather than sequential so two concurrent interceptions of the same
+ * path cannot collide, and it is removed on any failure so a failed write leaves no debris behind.
+ */
+export function writeFileAtomic(path, bytes) {
+  const temporary = join(dirname(path), `.${basename(path)}.dsh-os-${randomBytes(6).toString('hex')}.tmp`)
+  try {
+    writeFileSync(temporary, bytes)
+    renameSync(temporary, path)
+  } catch (error) {
+    try { rmSync(temporary, { force: true }) } catch { /* the failure that matters is the original */ }
+    throw error
+  }
+}
+
+// ---------------------------------------------------------------------------
+// per-tool handlers
+// ---------------------------------------------------------------------------
+
+/** Split an `output.text` slice into the `{ number, text }` records the built-in `read` reports. */
+function windowFromSlice(sliceText, offset, totalLines) {
+  const all = sliceText.split('\n')
+  // dsh-os splits on LF and a file ending in a newline therefore yields a final empty element. The
+  // built-in `read` does not report that trailing element as a line, so it is dropped here rather than
+  // inflating totalLines by one.
+  if (all.length > 0 && all[all.length - 1] === '') all.pop()
+  const lines = []
+  for (let index = 0; index < all.length; index += 1) {
+    const number = offset + index
+    if (number > totalLines) break
+    lines.push({ number, text: all[index] })
+  }
+  return lines
+}
+
+/** Run `file view` and return its envelope result. */
+async function viewFile(invocation, path, flags = []) {
+  return invokeForResult(invocation, 'file view', [path], flags)
+}
+
+/**
+ * Answer a built-in `read` call.
+ *
+ * The value must satisfy the built-in schema exactly (`path`, `offset`, `lines[{number,text}]`,
+ * `totalLines`, additionalProperties false), because that value is what the built-in renderer formats
+ * and what the built-in presentation metadata is derived from.
+ */
+async function handleRead(args, invocation) {
+  const path = String(args.file_path)
+  const offset = Number.isInteger(args.offset) && args.offset > 0 ? args.offset : 1
+  const limit = Number.isInteger(args.limit) && args.limit > 0 ? args.limit : 2000
+
+  const view = await viewFile(invocation, path)
+  // `lineCount` counts the trailing empty element the same way `split` does, so the reported total is
+  // taken from the slice arithmetic instead: the verb's own text is authoritative.
+  const text = String(view.text ?? '')
+  const endsWithNewline = text.endsWith('\n')
+  const allLines = text.split('\n')
+  if (endsWithNewline) allLines.pop()
+  const totalLines = allLines.length
+
+  const selected = allLines.slice(offset - 1, offset - 1 + limit)
+  const lines = selected.map((lineText, index) => ({ number: offset + index, text: lineText }))
+
+  return { path: view.path ?? path, offset, lines, totalLines }
+}
+
+/**
+ * Answer a built-in `write` call.
+ *
+ * `before` and `after` are the decoded text, matching what the built-in `read` reports for the same
+ * file, while the bytes actually landing on disk keep the target's original BOM and line endings. That
+ * split is deliberate: the values are compared by the model and diffed by the UI (both of which work in
+ * normalised text), and only the byte-level write needs the file's convention.
+ */
+async function handleWrite(args, invocation) {
+  const path = String(args.file_path)
+  const content = String(args.content ?? '')
+
+  const before = existsSync(path) ? decodeTextFile(readFileSync(path)) : null
+  const format = readTargetFormat(path)
+
+  writeFileAtomic(path, encodeTextForTarget(content, format))
+
+  // The verb is still consulted for the write itself only when the target did not exist: `file create`
+  // refuses to overwrite by contract, so an existing target is replaced here. A new target goes through
+  // the verb, which is where the parent-directory creation and the protected-path check live.
+  if (before === null) {
+    const created = await invokeForResult(invocation, 'file create', [path, content, format.bom ? 'utf-8-bom' : 'utf-8'], [], { allow: true })
+    return {
+      path: created.path ?? path,
+      operation: 'create',
+      before: null,
+      after: content,
+    }
+  }
+
+  return {
+    path,
+    operation: 'update',
+    before,
+    after: content,
+  }
+}
+
+/**
+ * Answer a built-in `edit` call.
+ *
+ * The literal replacement is performed on the decoded text — the same text the model was shown by
+ * `read` — and the result is written back in the target's own convention. Match counting mirrors the
+ * built-in contract: one match is required unless `replace_all` is set, and a violation throws so the
+ * caller falls back to the built-in tool rather than inventing a different answer.
+ */
+async function handleEdit(args, invocation) {
+  const path = String(args.file_path)
+  const oldString = String(args.old_string ?? '')
+  const newString = String(args.new_string ?? '')
+  const replaceAll = args.replace_all === true
+
+  if (oldString === '') throw new Error('old_string must be a non-empty string')
+  if (oldString === newString) throw new Error('old_string and new_string must differ')
+
+  const format = readTargetFormat(path)
+  if (!format.exists) throw new Error(`cannot edit '${path}': it does not exist`)
+  const before = decodeTextFile(readFileSync(path))
+
+  const occurrences = before.split(oldString).length - 1
+  if (occurrences === 0) throw new Error(`old_string was not found in ${path}`)
+  if (occurrences > 1 && !replaceAll) {
+    throw new Error(`old_string appears ${occurrences} times in ${path}; pass replace_all to replace every occurrence`)
+  }
+
+  const after = replaceAll
+    ? before.split(oldString).join(newString)
+    : before.replace(oldString, newString)
+
+  writeFileAtomic(path, encodeTextForTarget(after, format))
+
+  return { path, before, after }
+}
+
+/**
+ * Answer a built-in `pwsh` call.
+ *
+ * The value must satisfy the built-in foreground variant of the `oneOf` output schema, including
+ * `kind: "foreground"`, both stream objects with their `truncated` flags, and the null-able
+ * `exitCode`/`signal` pair.
+ *
+ * `signal` is always null: dsh-os reports a numeric exit status and does not surface the terminating
+ * signal separately, and inventing a value there would be a claim the envelope does not support.
+ */
+async function handlePwsh(args, invocation, timeoutMs) {
+  const command = String(args.command ?? '')
+  const workdir = typeof args.workdir === 'string' && args.workdir !== '' ? args.workdir : undefined
+  const requestedTimeout = Number.isFinite(args.timeoutMs) && args.timeoutMs > 0 ? args.timeoutMs : timeoutMs
+
+  // `pwsh -Command <command>` is what the built-in tool runs, so the same argv shape is handed to
+  // execute.command: the arguments are passed as separate argv elements and never spliced into a
+  // shell string.
+  const flags = ['--timeout', String(Math.round(requestedTimeout))]
+  if (workdir !== undefined) flags.push('--workdir', workdir)
+
+  const result = await invokeForResult(invocation, 'execute.command', ['pwsh', '-NoLogo', '-NoProfile', '-Command', command], flags, { allow: true, timeoutMs: requestedTimeout + 5000 })
+
+  const stdoutText = String(result.stdout ?? '')
+  const stderrText = String(result.stderr ?? '')
+
+  return {
+    kind: 'foreground',
+    exitCode: Number.isInteger(result.exitCode) ? result.exitCode : null,
+    signal: null,
+    timedOut: result.timedOut === true,
+    aborted: false,
+    timeoutMs: Math.round(requestedTimeout),
+    stdout: { text: stdoutText, truncated: result.stdoutTruncated === true },
+    stderr: { text: stderrText, truncated: result.stderrTruncated === true },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// plugin
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether a path can be forwarded at all.
+ *
+ * An absolute path is required because the built-in tools resolve relative paths against the session
+ * workspace root through `ctx.fs`, and this plugin has no equivalent of that resolution. Guessing the
+ * process working directory would read a different file than the one the model named, which is worse
+ * than not taking the call over.
+ */
+function forwardablePath(value) {
+  return typeof value === 'string' && value.trim() !== '' && isAbsolute(value)
+}
+
+/** Whether the call is one this row can answer without changing what the result means. */
+function eligible(tool, args) {
+  switch (tool) {
+    case 'read':
+    case 'write':
+    case 'edit':
+      return forwardablePath(args.file_path)
+    case 'pwsh':
+      // A background call's result is a harness job id, and this surface cannot produce one. The
+      // session-scoped sandbox escalation arguments are likewise the harness's own seam.
+      if (args.run_in_background === true) return false
+      if (args.sandbox_permissions !== undefined) return false
+      return typeof args.command === 'string' && args.command.trim() !== ''
+    default:
+      return false
+  }
+}
+
+export function apply(ctx, config = {}) {
+  const toolTimeoutMs = config.timeoutMs ?? 120000
+
+  ctx.on('tools/execute', async (exec, next) => {
+    const settings = ctx['dsh-os-settings']
+    if (settings === undefined || !settings.enabled()) return next()
+
+    const tool = exec?.name
+    if (!TAKEOVER_TOOLS.includes(tool)) return next()
+    if (!settings.toolEnabled(tool)) return next()
+
+    const args = exec.arguments ?? {}
+    if (!eligible(tool, args)) return next()
+
+    const invocation = resolveInvocation(config)
+    if (invocation === null) return next()
+
+    try {
+      let value
+      if (tool === 'read') value = await handleRead(args, invocation)
+      else if (tool === 'write') value = await handleWrite(args, invocation)
+      else if (tool === 'edit') value = await handleEdit(args, invocation)
+      else value = await handlePwsh(args, invocation, toolTimeoutMs)
+
+      settings.record(tool, exec, value)
+      // Returning without calling next() is what replaces the built-in body. The value still travels
+      // through the built-in output schema and renderer.
+      return { value }
+    } catch (error) {
+      // Fallback is the contract: a redirected call may change how a result is produced, never whether
+      // the caller gets one. The reason is recorded so the settings panel can show why.
+      settings.recordFallback(tool, exec, error)
+      return next()
+    }
+  })
+}
+
+/** Exported for tests: the mapping from built-in arguments onto dsh-os argv. */
+export const __internals = { eligible, handleRead, handleWrite, handleEdit, handlePwsh, windowFromSlice, statSync }