@hope_phenom/dsh-plugin-remote-use 0.0.0-stage → 0.2.24

package/lib/provider/out-of-process-helpers.js

@@ -0,0 +1,76 @@
+/**
+ * Local mirror of the out-of-process helper vocabulary from
+ * `@deepseek-ai/dsh-subagent` (its `lib/types/out-of-process.js`).
+ *
+ * WHY A MIRROR: the plugin must stay unit-testable without a live DSH, and this
+ * constant is a frozen contract that cannot drift meaningfully. To keep the mirror
+ * honest rather than a guess, `verifyAgainstUpstream()` compares it with the real
+ * package when that package is importable, and the plugin calls it at load.
+ *
+ * The upstream values are authoritative; if DSH ever changes the capability set,
+ * verification fails loudly instead of silently advertising a capability we cannot
+ * honor (DESIGN §2.2 C1).
+ *
+ * @module dsh-plugin-remote-use/out-of-process-helpers
+ */
+
+/**
+ * The capability advertisement of an out-of-process backend: NONE.
+ *
+ * A child in another process cannot honor parent-enforced start features
+ * (`agentOptions` / `outputSchema` / `maxDepth` / `toolFilter` / `persona`), so the
+ * subagent service rejects a request needing any of them BEFORE `start` runs. This
+ * must never be widened without implementing the corresponding enforcement.
+ */
+export const NO_START_CAPABILITIES = Object.freeze({
+  agentOptions: false,
+  outputSchema: false,
+  depthLimit: false,
+  toolFilter: false,
+  persona: false,
+})
+
+/**
+ * Maximum UTF-8 size a provider-authored diagnostic may have upstream.
+ * Kept here so our diagnostics are shaped like the ones DSH produces.
+ */
+export const MAX_SUBAGENT_DIAGNOSTIC_BYTES = 4096
+
+/**
+ * Compare the local mirror with the real package.
+ * @returns {Promise<{ok: boolean, reason?: string, upstream?: object}>}
+ */
+export async function verifyAgainstUpstream() {
+  let upstream
+  try {
+    upstream = await import('@deepseek-ai/dsh-subagent')
+  } catch (error) {
+    // Not importable in a bare unit-test environment; that is expected and not a fault.
+    return { ok: true, reason: `upstream not importable here: ${error instanceof Error ? error.message : String(error)}` }
+  }
+  const real = upstream?.NO_START_CAPABILITIES
+  if (real === undefined) return { ok: true, reason: 'upstream no longer exports NO_START_CAPABILITIES' }
+  const keys = new Set([...Object.keys(real), ...Object.keys(NO_START_CAPABILITIES)])
+  for (const k of keys) {
+    if (real[k] !== NO_START_CAPABILITIES[k]) {
+      return { ok: false, reason: `capability "${k}" differs: upstream=${real[k]} local=${NO_START_CAPABILITIES[k]}`, upstream: real }
+    }
+  }
+  return { ok: true, upstream: real }
+}
+
+/**
+ * Truncate a diagnostic to the upstream byte limit without splitting a UTF-8
+ * sequence, mirroring how DSH limits provider-authored detail.
+ * @param {string} text
+ * @returns {string}
+ */
+export function limitDiagnostic(text) {
+  const bytes = new TextEncoder().encode(text)
+  if (bytes.byteLength <= MAX_SUBAGENT_DIAGNOSTIC_BYTES) return text
+  const suffix = '\n[diagnostic truncated]'
+  const suffixBytes = new TextEncoder().encode(suffix).byteLength
+  let cut = MAX_SUBAGENT_DIAGNOSTIC_BYTES - suffixBytes
+  while (cut > 0 && (bytes[cut] & 0b1100_0000) === 0b1000_0000) cut -= 1
+  return new TextDecoder().decode(bytes.subarray(0, cut)) + suffix
+}

package/lib/provider/remote-provider.js

@@ -0,0 +1,261 @@
+/**
+ * The remote delegation provider.
+ *
+ * This is the piece that makes "call another machine like a subagent" true: it
+ * implements DSH's `SubagentProvider` seam, so the model sees a normal delegation
+ * tool and the service routes the request here. Nothing in DSH is modified.
+ *
+ * HARD CONSTRAINTS (DESIGN §2.2 — these are code facts, not choices):
+ *   C1  `capabilities` must be all false. The service validates the request against
+ *       them BEFORE `start()` and rejects anything it cannot honor, so advertising a
+ *       capability we do not implement would fail loudly at dispatch.
+ *   C2  No `prepareContinuable`. A continuable child is always materialized by the
+ *       LOCAL `ctx.agents.create/resume`, so an out-of-process provider cannot
+ *       support it. The tool row must therefore use `backgroundMode: one-shot`.
+ *   C3  `run.localAgent` must stay `undefined` -> no `subagent/catalog` entry ->
+ *       remote runs are invisible to `list_agents`. `TaskRegistry` compensates.
+ *   C6  `inheritsParentContext` must be false: the worker cannot see our session.
+ *
+ * @module dsh-plugin-remote-use/remote-provider
+ */
+
+import { NO_START_CAPABILITIES } from './out-of-process-helpers.js'
+import { assertUsableCwd } from '../core/task-cwd.js'
+
+// The rule lives in `core/task-cwd.js` because the WORKER's arming path needs the same answer
+// (it advertises the directory in its pairing string). Re-exported here because this module is
+// where it is ENFORCED on the dispatch path, and that is where callers look for it.
+export { assertUsableCwd }
+
+/** Delegation is refused with this code when the worker's self-check is not green. */
+export const GATE_REFUSED = 'REMOTE_WORKER_NOT_READY'
+
+/**
+ * @typedef {object} PeerRuntime
+ * @property {string} peerId
+ * @property {string} name
+ * @property {import('../bridge/acp-bridge.js').AcpBridge} bridge
+ * @property {() => Promise<object>} selfcheck     returns the gate report
+ * @property {string} defaultCwd
+ */
+
+export class RemoteProvider {
+  /**
+   * @param {object} opts
+   * @param {PeerRuntime} opts.peer
+   * @param {import('../core/task-registry.js').TaskRegistry} opts.registry
+   * @param {(req: object) => Promise<{optionId:string, source:string, reason:string, needsHuman:boolean}>} opts.decideApproval
+   *        Bound review-engine decision function. MUST implement the cache-miss and
+   *        tier-check rules; passing a permissive stub here is the vulnerability
+   *        found in DESIGN §10.0.1.
+   * @param {number} [opts.serialQueue]  max concurrent tasks per peer (DESIGN §7.3: 1)
+   * @param {string} [opts.workspaceRoot]  used by the tier check
+   */
+  constructor(opts) {
+    this.name = `remote-${opts.peer.peerId}`
+    /** C1: never advertise what an out-of-process worker cannot honor. */
+    this.capabilities = { ...NO_START_CAPABILITIES }
+    /** C6: the worker has no access to the delegating session. */
+    this.inheritsParentContext = false
+
+    this.peer = opts.peer
+    this.registry = opts.registry
+    this.decideApproval = opts.decideApproval
+    this.serialQueue = opts.serialQueue ?? 1
+    this.workspaceRoot = opts.workspaceRoot ?? ''
+    /** @type {Array<() => void>} */
+    this.waiters = []
+    this.running = 0
+  }
+
+  /**
+   * Establish a remote child. Fulfils only after the worker has accepted the task,
+   * so the caller always owns a live run or nothing (the seam's publication rule).
+   *
+   * @param {object} request  DSH's ResolvedSubagentStartRequest
+   * @returns {Promise<{id:string, localAgent:undefined, result:Promise<object>, dispose:() => Promise<void>}>}
+   */
+  async start(request) {
+    const prompt = blocksToText(request.prompt)
+    const label = request.label ?? ''
+    const cwd = this.peer.defaultCwd
+
+    // Fail early on a bad cwd. DSH's ACP server rejects a non-absolute `cwd` with
+    // -32602, and the error surfaces as an opaque turn failure -- better to say what
+    // is wrong here, before a session is even created.
+    const cwdProblem = assertUsableCwd(cwd)
+    if (cwdProblem !== '') {
+      const err = new Error(`remote worker "${this.peer.peerId}": ${cwdProblem}`)
+      err.code = 'REMOTE_BAD_CWD'
+      throw err
+    }
+
+    // ---- gate: refuse rather than fail halfway (DESIGN §5.10.6) -------------
+    const report = await this.peer.selfcheck()
+    const gate = this.#evaluateGate(report)
+    if (gate.blocked) {
+      // A refusal must surface as a rejected start, so no run is published.
+      const err = new Error(gate.message)
+      err.code = GATE_REFUSED
+      err.details = gate.details
+      throw err
+    }
+
+    // ---- serial queue: GUI is an exclusive resource (DESIGN §7.3) -----------
+    await this.#acquire()
+
+    const task = this.registry.create({ peerId: this.peer.peerId, label, prompt, cwd })
+    this.registry.markRunning(task.taskId)
+
+    let disposed = false
+    const release = () => { if (!disposed) { disposed = true; this.#release() } }
+
+    // The run's result must NEVER reject: a rejected promise after publication
+    // would strand the caller's foreground/background bookkeeping. The catch also
+    // settles the registry -- otherwise a bridge failure would leave a phantom
+    // "running" task that `remote_agents` keeps reporting forever.
+    const result = this.#runTask(task, { prompt, cwd })
+      .catch((error) => {
+        const diagnostic = error instanceof Error ? error.message : String(error)
+        this.registry.settle(task.taskId, { state: 'error', stopReason: 'error', diagnostic })
+        return {
+          output: [{ type: 'text', text: '' }],
+          stopReason: 'error',
+          diagnostic,
+        }
+      })
+      .finally(release)
+
+    return {
+      id: task.taskId,
+      localAgent: undefined,          // C3
+      result,
+      dispose: async () => {
+        // Idempotent as a WHOLE: a second dispose must neither release the queue
+        // slot again nor send a second cancel to the worker.
+        if (disposed) return
+        release()
+        try { await this.peer.bridge.cancel() } catch { /* cancellation is best effort */ }
+      },
+    }
+  }
+
+  // NOTE: intentionally no `prepareContinuable` (C2).
+
+  /**
+   * Drive the task to a `SubagentResult`.
+   * @param {import('../core/task-registry.js').RemoteTask} task
+   * @param {{ prompt: string, cwd: string }} input
+   */
+  async #runTask(task, input) {
+    const outcome = await this.peer.bridge.startTask({
+      cwd: input.cwd,
+      prompt: input.prompt,
+      onUpdate: (evt) => {
+        if (evt.kind === 'tool_call' && evt.tool !== undefined) {
+          this.registry.noteToolCall(task.taskId, evt.tool.toolName ?? '?')
+        }
+        if (evt.kind === 'usage' && evt.usage !== undefined) {
+          this.registry.setUsage(task.taskId, evt.usage)
+        }
+      },
+      onApproval: async (ask) => {
+        this.registry.setWaitingForApproval(task.taskId, true)
+        try {
+          const decision = await this.decideApproval({
+            taskId: task.taskId,
+            toolCallId: ask.toolCallId,
+            toolName: ask.toolName,
+            rawInput: ask.rawInput,
+          })
+          return decision.optionId
+        } finally {
+          this.registry.setWaitingForApproval(task.taskId, false)
+        }
+      },
+    })
+
+    const state = outcome.stopReason === 'completed' ? 'completed' : outcome.stopReason
+    this.registry.settle(task.taskId, {
+      state,
+      stopReason: outcome.stopReason,
+      diagnostic: outcome.diagnostic,
+      // The answer is retained in the registry, not just returned through `result`. A background
+      // caller has already stopped awaiting `result` by the time this line runs, so this is the
+      // only place the text can reach it (PITFALLS F15). `stopReason: 'error'` still carries
+      // whatever the worker managed to say before it failed.
+      output: outcome.output,
+    })
+
+    return {
+      output: [{ type: 'text', text: outcome.output ?? '' }],
+      ...(outcome.diagnostic === undefined ? {} : { diagnostic: outcome.diagnostic }),
+      stopReason: outcome.stopReason,
+    }
+  }
+
+  /**
+   * Turn a self-check report into a dispatch decision.
+   *
+   * `no-interactive-session` is NOT a fault: the worker is healthy but nobody is
+   * logged in. The two must produce different diagnostics or operators chase the
+   * wrong problem (DESIGN §5.10.6).
+   * @param {object} report
+   */
+  #evaluateGate(report) {
+    if (report === null || report === undefined) {
+      return { blocked: true, message: 'remote worker did not return a self-check report', details: {} }
+    }
+    const checks = Array.isArray(report.checks) ? report.checks : []
+    const failed = checks.filter((c) => c.severity === 'blocking' && c.status === 'fail')
+
+    const sessionMissing = report.sessionSegment === 'unavailable'
+      || checks.some((c) => c.id === 'S8' && c.status === 'unchecked')
+
+    if (sessionMissing) {
+      return {
+        blocked: true,
+        message: 'remote worker has no interactive session: someone must be logged in on it '
+          + '(the desktop must be unlocked for input injection to work)',
+        details: { reason: 'no-interactive-session', checks: failed.map((c) => c.id) },
+      }
+    }
+    if (failed.length > 0) {
+      return {
+        blocked: true,
+        message: `remote worker is not ready: ${failed.map((c) => `${c.id} ${c.name} (expected ${c.expected}, actual ${c.actual})`).join('; ')}`,
+        details: { reason: 'selfcheck-failed', checks: failed.map((c) => c.id) },
+      }
+    }
+    return { blocked: false, message: '', details: {} }
+  }
+
+  /** FIFO gate so one worker runs one task at a time. */
+  async #acquire() {
+    if (this.running < this.serialQueue) { this.running += 1; return }
+    await new Promise((resolve) => this.waiters.push(resolve))
+    this.running += 1
+  }
+
+  #release() {
+    this.running = Math.max(0, this.running - 1)
+    const next = this.waiters.shift()
+    if (next !== undefined) next()
+  }
+}
+
+/**
+ * Flatten DSH content blocks to plain text for the ACP prompt.
+ * @param {unknown} blocks
+ * @returns {string}
+ */
+export function blocksToText(blocks) {
+  if (typeof blocks === 'string') return blocks
+  if (!Array.isArray(blocks)) return ''
+  return blocks
+    .map((b) => (b !== null && typeof b === 'object' && typeof (/** @type {any} */ (b).text) === 'string'
+      ? /** @type {any} */ (b).text
+      : ''))
+    .filter((s) => s !== '')
+    .join('\n')
+}

package/lib/tools/mediator-shim.mjs

@@ -0,0 +1,180 @@
+/**
+ * sandbox-mediator-shim.mjs -- run the Windows ACL sandbox runner from a console-subsystem
+ * mediator.
+ *
+ * THE PROBLEM
+ *   `dsh-sandbox-local`'s default mediator is `process.execPath`, which in this deployment is
+ *   `DeepSeek Harness.exe` -- a GUI-subsystem image. Windows never auto-allocates a console
+ *   to a GUI-subsystem image, so the WRITE_RESTRICTED child the runner creates has no console
+ *   to inherit and dies during DLL initialization with 0xC0000142 (STATUS_DLL_INIT_FAILED).
+ *   Every shell command fails, with no output at all.
+ *
+ *   Measured on this machine, same runner and args, only the interpreter varied (8/8 valid):
+ *     node.exe (console subsystem)          4/4 exit 0, child produced its output
+ *     DeepSeek Harness.exe (GUI subsystem)  4/4 exit 0xC0000142, no output
+ *
+ * WHY A SHIM AND NOT `runnerCommand` POINTED AT THE RUNNER DIRECTLY
+ *   `sandbox-local.confine()` prepends `bwrapProfileArgs(policy)` to a configured
+ *   `runnerCommand` unconditionally -- a bubblewrap dialect (`--ro-bind`, `--bind`,
+ *   `--tmpfs`, ...) that the Windows runner rejects with
+ *   `windows-acl-run: unknown argument: --ro-bind`. `runnerCommand` is the "operator
+ *   asserts this is a bwrap-compatible runner" path, not a way to swap the win32 rung.
+ *
+ *   So the shim is named as the runner and translates the two dialects. Being launched as
+ *   `node.exe` is the whole point: a console-subsystem image is auto-allocated a console,
+ *   which is what the restricted child needs.
+ *
+ * CONTRACT
+ *   in : <bwrap profile args> -- <command argv...>
+ *   out: spawns `node.exe <windows-acl runner> --workspace .. --temp .. --mode .. -- <argv>`
+ *        with the shim's own stdio inherited, and mirrors the exit code.
+ *
+ * LIMITATIONS -- deliberate and stated rather than hidden:
+ *   * `--bind <root>` is emitted ONLY in workspace-write mode, so in read-only mode the
+ *     workspace root is not on the command line. The shim then falls back to
+ *     DSH_SANDBOX_WORKSPACE, then to the current directory. Read-only issues no workspace
+ *     write grant, so the value only needs to name an existing directory.
+ *   * `--unshare-pid` and `--die-with-parent` have no Windows equivalent and are dropped.
+ *     Process containment comes from the runner's own job object.
+ *   * A bubblewrap argument this shim does not recognise is a HARD ERROR, never ignored:
+ *     silently dropping a confinement argument would weaken the sandbox without saying so.
+ */
+import { spawn } from 'node:child_process'
+import { existsSync, statSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const RUNNER = process.env.DSH_SANDBOX_RUNNER
+  ?? join(HERE, 'node_modules', '@deepseek-ai', 'dsh-sandbox-windows-acl', 'lib', 'runner.js')
+
+function die(message) {
+  // The runner's own failure signature prefix, so dsh-sandbox-local's
+  // `runnerFailureSignatures` match catches this and reports it as a sandbox failure
+  // rather than as an opaque non-zero exit.
+  process.stderr.write(`windows-acl-run: shim: ${message}\n`)
+  process.exit(1)
+}
+
+const argv = process.argv.slice(2)
+const sep = argv.indexOf('--')
+if (sep < 0) die('missing "--" separator')
+const profile = argv.slice(0, sep)
+const command = argv.slice(sep + 1)
+if (command.length === 0) die('no command after "--"')
+
+if (!existsSync(RUNNER)) die(`runner not found at ${RUNNER}`)
+
+// ---- translate the bubblewrap dialect -------------------------------------
+let mode = 'read-only'
+let workspace = ''
+let temp = ''
+const dropped = []
+
+for (let i = 0; i < profile.length; i += 1) {
+  const a = profile[i]
+  const next = () => {
+    const v = profile[i + 1]
+    if (v === undefined) die(`missing value after ${a}`)
+    i += 1
+    return v
+  }
+  switch (a) {
+    case '--ro-bind': {
+      // `--ro-bind <src> <dest>`: read-only bind. The Windows rung is always
+      // read-everything, so this is represented by the mode, not by path grants.
+      next(); next()
+      break
+    }
+    case '--bind': {
+      // `--bind <src> <dest>`: writable bind -- the workspace, and the only place the
+      // workspace root appears on the command line.
+      const src = next()
+      next()
+      mode = 'workspace-write'
+      workspace = src
+      break
+    }
+    case '--tmpfs': {
+      // bwrapProfileArgs hardcodes the Linux path `/tmp`, which does not exist here. Take
+      // the value only when it names a real directory; otherwise fall back to the platform
+      // temp. This one IS a silent substitution, so it is recorded on stderr for anyone
+      // debugging with DSH_SANDBOX_SHIM_DEBUG=1 -- it never affects what is writable,
+      // because the runner grants its own private temp child under whatever root it gets.
+      const value = next()
+      if (existsSync(value)) temp = value
+      else if (process.env.DSH_SANDBOX_SHIM_DEBUG === '1') {
+        process.stderr.write(`windows-acl-shim-debug: ignoring tmpfs ${value} (absent on this platform); using ${tmpdir()}\n`)
+      }
+      break
+    }
+    case '--dev':
+    case '--proc': {
+      next()
+      break
+    }
+    case '--unshare-pid':
+    case '--die-with-parent': {
+      dropped.push(a)
+      break
+    }
+    default:
+      die(`unrecognised profile argument "${a}"`)
+  }
+}
+
+if (workspace === '') {
+  // Read-only mode carries no --bind, so the workspace root is not on the command line.
+  // The workspace grant is inert in read-only, so any stable existing directory satisfies
+  // the runner's argument contract. `process.cwd()` is NOT used: it depends on whoever
+  // launched the mediator (an SSH session put it at C:\Users\worker, which then appeared to
+  // contain the temp directory). The mediator's own directory is deterministic.
+  workspace = process.env.DSH_SANDBOX_WORKSPACE ?? HERE
+}
+if (temp === '') temp = tmpdir()
+
+for (const p of [workspace, temp]) {
+  try {
+    if (!statSync(p).isDirectory()) die(`not a directory: ${p}`)
+  } catch {
+    die(`does not exist: ${p}`)
+  }
+}
+// The runner refuses a temp root inside the workspace; keep that invariant explicit here so
+// the failure names the shim's translation rather than surfacing as an opaque runner error.
+//
+// The comparison is BOUNDARY-AWARE: a plain prefix test made C:\Users\worker appear to
+// contain C:\Users\worker\AppData\Local\Temp, which is a different relationship from
+// containment by path segment.
+function containsPath(parent, child) {
+  const norm = (p) => p.replace(/[\\/]+$/, '').toLowerCase()
+  const a = norm(parent)
+  const b = norm(child)
+  if (a === b) return true
+  const sep = a.endsWith('\\') || a.endsWith('/') ? '' : (a.includes('\\') ? '\\' : '/')
+  return b.startsWith(a + sep)
+}
+if (containsPath(workspace, temp)) {
+  die(`temp root ${temp} is inside the workspace ${workspace}`)
+}
+
+const runnerArgs = [
+  RUNNER,
+  '--workspace', workspace,
+  '--temp', temp,
+  '--mode', mode,
+  '--',
+  ...command,
+]
+
+// `process.execPath` is node.exe for this shim, i.e. a console-subsystem image -- which is
+// exactly the property that makes the restricted child work. stdio is inherited so DSH
+// still receives the command's output through the pipes it set up.
+const child = spawn(process.execPath, runnerArgs, { stdio: 'inherit', windowsHide: false })
+
+child.on('error', (error) => die(`could not spawn runner: ${error.message}`))
+child.on('exit', (code, signal) => {
+  if (signal !== null) process.exit(1)
+  process.exit(code ?? 1)
+})