dsh-remote-workspaces 0.1.0

package/src/containment.js

@@ -0,0 +1,71 @@
+/**
+ * Workspace-write containment, mirrored from the harness's
+ * `@deepseek-ai/dsh-sandbox` (roots.ts) and `@deepseek-ai/dsh-fs-sandbox`
+ * (containment.ts) so the plugin's LOCAL half fences writes with the exact
+ * same semantics without importing harness packages (which would dual-package
+ * the Cordis context).
+ *
+ * `workspace-write` = "the policy's workspace root plus the platform temp
+ * areas", canonicalized; containment is lexical-prefix with a filesystem-
+ * identity fallback for Windows 8.3/case aliases.
+ */
+
+import { realpathSync } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import { dirname, sep } from 'node:path'
+import { tmpdir } from 'node:os'
+
+const MISSING_CODES = new Set(['ENOENT', 'ENOTDIR'])
+
+function canonicalPath(path) {
+  try {
+    return realpathSync.native(path)
+  } catch {
+    // Missing root matches nothing until it exists — the conservative outcome.
+    return path
+  }
+}
+
+/** The canonical writable roots for a policy (empty under anything but workspace-write). */
+export function writableRoots(policy) {
+  if (policy === undefined || policy.mode !== 'workspace-write') return []
+  return [...new Set([policy.workspaceRoot, '/tmp', tmpdir()].map(canonicalPath))]
+}
+
+function comparablePath(path, caseSensitive) {
+  return caseSensitive ? path : path.toLowerCase()
+}
+
+function isLexicallyUnder(path, root, caseSensitive) {
+  const target = comparablePath(path, caseSensitive)
+  const base = comparablePath(root, caseSensitive)
+  if (target === base) return true
+  const prefix = base.endsWith(sep) ? base : base + sep
+  return target.startsWith(prefix)
+}
+
+async function statIfPresent(path) {
+  try {
+    return await stat(path, { bigint: true })
+  } catch (error) {
+    if (MISSING_CODES.has(error.code)) return undefined
+    throw error
+  }
+}
+
+/** Whether `path` is `root` or a descendant of it (canonical spellings). */
+export async function isPathUnder(path, root, caseSensitive = process.platform !== 'win32') {
+  if (isLexicallyUnder(path, root, caseSensitive)) return true
+  const rootInfo = await statIfPresent(root)
+  if (!rootInfo) return false
+  let ancestor = path
+  while (true) {
+    const info = await statIfPresent(ancestor)
+    if (info && info.dev === rootInfo.dev && info.ino === rootInfo.ino) return true
+    const parent = dirname(ancestor)
+    if (parent === ancestor) return false
+    ancestor = parent
+  }
+}
+
+export default { writableRoots, isPathUnder }

package/src/errors.js

@@ -0,0 +1,17 @@
+/**
+ * A minimal error shape the backends throw, mirroring `@deepseek-ai/dsh-fs`
+ * `FsError` (`name` + stable `code` + `message`). It is a PLAIN `Error`, not an
+ * instance of the harness's `FsError`/`HarnessError` (the plugin cannot import
+ * `@deepseek-ai/*` packages without dual-packaging the Cordis context), so the
+ * tool layer's `instanceof FsError` enrichments (the `[sandbox: …]` marker, the
+ * escalation hint, the stale-version remedy) do not apply — a denial surfaces
+ * as the plain error message. Consumers that read `.code` structurally still
+ * get the stable code.
+ */
+
+export function fsError(code, message, cause) {
+  const error = new Error(message, cause === undefined ? undefined : { cause })
+  error.name = 'FsError'
+  error.code = code
+  return error
+}

package/src/fs-sftp.js

@@ -0,0 +1,231 @@
+/**
+ * SFTP remote backend (the remote half of the routing provider).
+ *
+ * A plain backend over the ssh2 SFTP channel — does NOT extend the
+ * `FileSystem` service, so the routing provider can hold it without registering
+ * `ctx.fs`. Implements the same 12 operations on plain targets and version
+ * strings, using SFTP primitives (readdir/stat/readFile/writeFile/rename) so
+ * type detection and ENOENT handling are locale-independent (a shell `stat`
+ * localized to the remote's locale broke type/absence detection).
+ */
+
+import { posix } from 'node:path'
+import { createHash } from 'node:crypto'
+import { fsError } from './errors.js'
+
+function isMissing(error) {
+  const code = error && error.code
+  const message = error && error.message ? String(error.message) : ''
+  return code === 2 || code === 'ENOENT' || /no such file|not exist/i.test(message)
+}
+
+/** File type from ssh2 Stats/attrs, with a mode-bits fallback. */
+function typeOf(st) {
+  if (st && typeof st.isDirectory === 'function' && st.isDirectory()) return 'directory'
+  if (st && typeof st.isFile === 'function' && st.isFile()) return 'file'
+  if (st && typeof st.mode === 'number') {
+    if ((st.mode & 0o170000) === 0o040000) return 'directory'
+    if ((st.mode & 0o170000) === 0o100000) return 'file'
+  }
+  return 'other'
+}
+
+export class SftpBackend {
+  constructor(client) {
+    this.client = client
+    this._sftp = undefined
+  }
+
+  /** Lazily open ONE persistent SFTP channel per backend (host). */
+  async sftp() {
+    if (this._sftp === undefined) this._sftp = await this.client.sftp()
+    return this._sftp
+  }
+
+  async resolve(path, opts = {}) {
+    if (typeof path !== 'string' || path.trim() === '') {
+      throw fsError('FS_NOT_FOUND', 'file_path must be a non-empty string')
+    }
+    const base = opts.cwd ?? '/'
+    const displayPath = posix.resolve(base, path)
+    const sftp = await this.sftp()
+    let targetKey = displayPath
+    try { targetKey = await sftp.realpath(displayPath) } catch { /* about-to-be-created path keeps its spelling */ }
+    return { targetKey, displayPath }
+  }
+
+  processPath(target) {
+    return target.targetKey
+  }
+
+  fileUrl(target) {
+    return `ssh://${this.client.host}${target.targetKey}`
+  }
+
+  contains(parent, child) {
+    const rel = posix.relative(parent.targetKey, child.targetKey)
+    return rel === '' || (rel !== '..' && !rel.startsWith('../') && !posix.isAbsolute(rel))
+  }
+
+  async stat(target) {
+    const sftp = await this.sftp()
+    let st
+    try {
+      st = await sftp.stat(target.targetKey)
+    } catch (error) {
+      if (isMissing(error)) return undefined
+      throw fsError('FS_IO_ERROR', `cannot stat "${target.displayPath}": ${error.message}`, error)
+    }
+    const type = typeOf(st)
+    const mtimeMs = Math.round((typeof st.mtime === 'number' ? st.mtime : 0) * 1000)
+    return {
+      version: `mtime:${mtimeMs}:size:${st.size ?? 0}`,
+      type,
+      ...(type === 'file' ? { size: st.size } : {}),
+    }
+  }
+
+  async lstat(path, opts = {}) {
+    // This facade has no no-follow stat; map to resolve + stat.
+    const target = await this.resolve(path, opts)
+    return this.stat(target)
+  }
+
+  async readText(target) {
+    const sftp = await this.sftp()
+    let buf
+    try {
+      buf = await sftp.readFile(target.targetKey)
+    } catch (error) {
+      throw fsError('FS_IO_ERROR', `cannot read "${target.displayPath}": ${error.message}`, error)
+    }
+    const text = Buffer.from(buf).toString('utf8')
+    if (text.includes('\0')) throw fsError('FS_NOT_TEXT', `cannot read "${target.displayPath}": binary file`)
+    return text
+  }
+
+  async streamText(target) {
+    const text = await this.readText(target)
+    return {
+      async *[Symbol.asyncIterator]() {
+        yield text
+      },
+    }
+  }
+
+  async readBytes(target, signal, maxBytes) {
+    const info = await this.stat(target)
+    if (info === undefined) throw fsError('FS_NOT_FOUND', `cannot read "${target.displayPath}": not found`)
+    if (info.type !== 'file') throw fsError('FS_NOT_REGULAR_FILE', `cannot read "${target.displayPath}": not a regular file`)
+    if (info.size !== undefined && info.size > maxBytes) {
+      throw fsError('FS_TOO_LARGE', `cannot read "${target.displayPath}": ${info.size} bytes exceeds the ${maxBytes}-byte limit`)
+    }
+    const sftp = await this.sftp()
+    const buf = await sftp.readFile(target.targetKey)
+    return new Uint8Array(Buffer.from(buf))
+  }
+
+  async listDir(target) {
+    const sftp = await this.sftp()
+    let entries
+    try {
+      entries = await sftp.readdir(target.targetKey)
+    } catch (error) {
+      if (isMissing(error)) throw fsError('FS_NOT_FOUND', `cannot list "${target.displayPath}": not found`)
+      throw fsError('FS_IO_ERROR', `cannot list "${target.displayPath}": ${error.message}`, error)
+    }
+    return (Array.isArray(entries) ? entries : [])
+      .filter((e) => e && e.filename !== '.' && e.filename !== '..')
+      .map((e) => ({
+        name: e.filename,
+        type: typeOf(e.attrs ?? {}),
+        target: {
+          targetKey: posix.join(target.targetKey, e.filename),
+          displayPath: posix.join(target.displayPath, e.filename),
+        },
+      }))
+      .sort((a, b) => a.name.localeCompare(b.name))
+  }
+
+  async writeText(target, content, expected) {
+    const existing = await this.stat(target)
+    if (existing !== undefined && existing.type !== 'file') {
+      throw fsError('FS_NOT_REGULAR_FILE', `cannot write "${target.displayPath}": not a regular file`)
+    }
+    if (expected && expected.kind === 'createIfAbsent' && existing !== undefined) {
+      throw fsError('FS_NOT_OBSERVED', `cannot overwrite existing "${target.displayPath}" without reading it first`)
+    }
+    if (expected && expected.kind === 'replaceIfVersion') {
+      if (existing === undefined || existing.version !== expected.version) {
+        throw fsError('FS_STALE_VERSION', `cannot write "${target.displayPath}": file changed since it was read`)
+      }
+    }
+    let before = null
+    if (existing !== undefined && existing.type === 'file') {
+      try { before = await this.readText(target) } catch { before = null }
+    }
+    await this.atomicWrite(target, content)
+    await this.verifyWrite(target, content)
+    const after = await this.stat(target)
+    return { operation: existing === undefined ? 'create' : 'update', version: after.version, before, after: content }
+  }
+
+  async editText(target, edit, expected) {
+    const existing = await this.stat(target)
+    if (existing === undefined) throw fsError('FS_STALE_VERSION', `cannot edit "${target.displayPath}": file changed since it was read`)
+    if (existing.type !== 'file') throw fsError('FS_NOT_REGULAR_FILE', `cannot edit "${target.displayPath}": not a regular file`)
+    if (expected && existing.version !== expected.version) {
+      throw fsError('FS_STALE_VERSION', `cannot edit "${target.displayPath}": file changed since it was read`)
+    }
+    const before = await this.readText(target)
+    const oldString = edit.oldString
+    if (!oldString) throw fsError('FS_EDIT_NOT_FOUND', `cannot edit "${target.displayPath}": old_string must be non-empty`)
+    let matches = 0
+    let offset = 0
+    while (true) {
+      const found = before.indexOf(oldString, offset)
+      if (found < 0) break
+      matches += 1
+      offset = found + oldString.length
+    }
+    if (matches === 0) throw fsError('FS_EDIT_NOT_FOUND', `cannot edit "${target.displayPath}": old_string was not found`)
+    if (!edit.replaceAll && matches !== 1) {
+      throw fsError('FS_AMBIGUOUS_EDIT', `cannot edit "${target.displayPath}": old_string matched ${matches} times`)
+    }
+    const after = edit.replaceAll ? before.split(oldString).join(edit.newString) : before.replace(oldString, edit.newString)
+    await this.atomicWrite(target, after)
+    await this.verifyWrite(target, after)
+    const st = await this.stat(target)
+    return { version: st.version, before, after }
+  }
+
+  /** Atomic write: temp file in the same dir, then rename over the target. */
+  async atomicWrite(target, content) {
+    const sftp = await this.sftp()
+    const tmp = posix.join(posix.dirname(target.targetKey), `.dsh-${posix.basename(target.targetKey)}.tmp-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+    try {
+      await sftp.writeFile(tmp, Buffer.from(content, 'utf8'))
+      try { await sftp.unlink(target.targetKey) } catch { /* target absent — first upload */ }
+      await sftp.rename(tmp, target.targetKey)
+    } catch (error) {
+      await sftp.unlink(tmp).catch(() => {})
+      throw fsError('FS_IO_ERROR', `cannot write "${target.targetKey}": ${error.message}`, error)
+    }
+  }
+
+  /**
+   * Post-write verification: compare the on-disk sha256 to the intended bytes
+   * (mirrors hermes-agent's write_file check). A mismatch is a hard error, so
+   * silent server-side truncation/corruption never reaches the caller. Skipped
+   * when the remote has no `sha256sum`/`shasum`.
+   */
+  async verifyWrite(target, content) {
+    const expected = createHash('sha256').update(content, 'utf8').digest('hex')
+    const actual = await this.client.sha256(target.targetKey)
+    if (actual !== undefined && actual !== expected) {
+      throw fsError('FS_IO_ERROR', `post-write verification failed for "${target.displayPath}": on-disk content does not match what was written`)
+    }
+  }
+}
+
+export default SftpBackend

package/src/index.js

@@ -0,0 +1,327 @@
+import { existsSync } from 'node:fs'
+import { SshClient, defaultSshConfigPath, hostsFromConfig, shellQuote, clientForHost } from './transport.js'
+import { loadMachines, sanitizeMachine, upsertMachine, removeMachine, machineById, machineForRemote, ensureSecretsEncrypted } from './machine-store.js'
+import { ensureAnchor } from './anchor.js'
+import { RoutingFileSystem } from './routing-fs.js'
+import { SshShellExecutor } from './shell-exec.js'
+import { registerAnchor, unregisterAnchor, findByCwd } from './registry.js'
+import { applySearchTools } from './search.js'
+
+export { parseSshConfig, expandTilde } from './ssh-config.js'
+export { SshClient, hostsFromConfig, shellQuote, defaultSshConfigPath, clientForHost } from './transport.js'
+export { SftpBackend } from './fs-sftp.js'
+export { LocalBackend } from './local-backend.js'
+export { parseSshUri, isRemoteCwd } from './ssh-uri.js'
+export { fsError } from './errors.js'
+export { RoutingFileSystem } from './routing-fs.js'
+export { SshShellExecutor } from './shell-exec.js'
+export { loadMachines, sanitizeMachine, upsertMachine, removeMachine, machinesPath } from './machine-store.js'
+export { registerAnchor, unregisterAnchor, findByCwd, loadAnchors } from './registry.js'
+
+/**
+ * Host half of the SSH remote workspace bundle (`dsh-remote-workspaces`).
+ *
+ * Publishes the routing `ctx.fs` and `ctx.shell` (local half sandboxed through
+ * the harness's policy/sandbox/subprocess services; remote half SFTP/ssh2 exec),
+ * plus the `remoteWorkspaces` Remote namespace for the "远程工作区" settings
+ * page: a persistent multi-machine SSH registry, `~/.ssh/config` import,
+ * connection test, remote directory browsing, and opening a remote directory
+ * as a workspace (an empty LOCAL anchor directory registered in the routing
+ * registry — all file/command I/O then lands on the remote, never the anchor).
+ */
+
+export const name = 'dsh-remote-workspaces'
+
+// ---------------------------------------------------------------------------
+// Remote contract. The client half (src/client.js) keeps an identical copy.
+// ---------------------------------------------------------------------------
+const PACKAGE = 'dsh-remote-workspaces'
+const NAMESPACE = 'remoteWorkspaces'
+
+const JSON_CODEC = Object.freeze({
+  mode: 'strict',
+  typeSymbol: 'JsonValue',
+  schema: Object.freeze({ parse(value) { return value } }),
+})
+
+function jsonParameter(name) {
+  return { name, wire: name, source: 'json', codec: JSON_CODEC }
+}
+
+function invocation(method, parameters = []) {
+  return {
+    id: `${NAMESPACE}/${method}`,
+    service: NAMESPACE,
+    namespace: NAMESPACE,
+    method,
+    invocation: { kind: 'direct' },
+    parameters,
+    result: JSON_CODEC,
+  }
+}
+
+const INVOCATIONS = [
+  invocation('listMachines'),
+  invocation('saveMachine', [jsonParameter('machine')]),
+  invocation('deleteMachine', [jsonParameter('id')]),
+  invocation('listSshAliases'),
+  invocation('sshAliasDetail', [jsonParameter('alias')]),
+  invocation('testConnection', [jsonParameter('machine')]),
+  invocation('listRemoteDir', [jsonParameter('machine'), jsonParameter('path')]),
+  invocation('openRemoteWorkspace', [jsonParameter('machine'), jsonParameter('path')]),
+]
+
+/** Build an `SshClient` from a machine record (alias/host/port/user/identityFile). */
+function sshClientFor(machine) {
+  const m = machine ?? {}
+  // Secrets never ride the browser wire (sanitizeMachine strips them), so a
+  // connection for a saved machine recovers its password/passphrase from the
+  // store by id. A machine being tested before saving may still carry them.
+  const stored = m.id !== undefined ? machineById(m.id) : undefined
+  return new SshClient({
+    alias: m.alias,
+    host: m.host,
+    user: m.user,
+    port: m.port,
+    identityFile: m.identityFile,
+    password: m.password ?? stored?.password,
+    passphrase: m.passphrase ?? stored?.passphrase,
+  })
+}
+
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * Build an `SshClient` for a remote host, preferring a saved machine's
+ * credentials (password/identityFile/passphrase) and falling back to
+ * `~/.ssh/config`. The routing fs + shell providers use this so remote I/O
+ * authenticates exactly like the settings "test connection" path.
+ */
+function clientForRemote(host, user, port) {
+  const machine = machineForRemote({ host, port, user })
+  return machine ? sshClientFor(machine) : clientForHost(host)
+}
+
+/**
+ * Resolve a raw browse path (home, `~`, `~/x`, relative, or absolute) to an
+ * absolute remote path so the client can navigate "up" past home to `/` and
+ * display a real path.
+ */
+async function resolveRemotePath(client, raw) {
+  const trimmed = raw === undefined || raw === null ? '' : String(raw).trim()
+  let sftp
+  try {
+    if (trimmed === '' || trimmed === '~' || trimmed === '~/') {
+      sftp = await client.sftp()
+      return await sftp.realpath('.')
+    }
+    if (trimmed.startsWith('~/')) {
+      sftp = await client.sftp()
+      const home = String(await sftp.realpath('.')).replace(/\/+$/, '')
+      return `${home}/${trimmed.slice(2)}`
+    }
+    if (!trimmed.startsWith('/')) {
+      sftp = await client.sftp()
+      return await sftp.realpath(trimmed)
+    }
+    return trimmed
+  } finally {
+    if (sftp) sftp.end()
+  }
+}
+
+/**
+ * Host owner of the `remoteWorkspaces` Remote namespace. Every method returns
+ * only lossless-JSON data and never echoes stored secrets back to the browser.
+ */
+function remoteWorkspacesService() {
+  return {
+    listMachines() {
+      return { ok: true, machines: loadMachines().map(sanitizeMachine) }
+    },
+
+    saveMachine(machine) {
+      try {
+        const saved = upsertMachine(machine ?? {})
+        return { ok: true, machine: saved }
+      } catch (error) {
+        return { ok: false, error: messageOf(error) }
+      }
+    },
+
+    deleteMachine(id) {
+      removeMachine(id)
+      return { ok: true }
+    },
+
+    listSshAliases() {
+      const path = defaultSshConfigPath()
+      if (!existsSync(path)) return { ok: true, path, aliases: [] }
+      try {
+        return { ok: true, path, aliases: hostsFromConfig(path).map((entry) => entry.alias) }
+      } catch (error) {
+        return { ok: false, error: messageOf(error) }
+      }
+    },
+
+    sshAliasDetail(alias) {
+      const host = hostsFromConfig(defaultSshConfigPath()).find((entry) => entry.alias === alias)
+      if (host === undefined) return { ok: false, error: `未在 ~/.ssh/config 找到别名 "${alias}"` }
+      return {
+        ok: true,
+        machine: sanitizeMachine({ ...host, id: undefined, password: undefined, passphrase: undefined }),
+      }
+    },
+
+    async testConnection(machine) {
+      const client = sshClientFor(machine)
+      const result = await client.run('echo ok')
+      if (result.ok) return { ok: true, ms: result.ms }
+      return { ok: false, ms: result.ms, error: (result.stderr ?? '').trim() || result.error || '连接失败' }
+    },
+
+    async listRemoteDir(machine, path) {
+      // `-A` hides `.`/`..`, `-p` appends `/` to directories, `-1` one per line.
+      const client = sshClientFor(machine)
+      let absPath
+      try {
+        absPath = await resolveRemotePath(client, path)
+      } catch (error) {
+        return { ok: false, error: `无法解析目录：${messageOf(error)}` }
+      }
+      const command = absPath === '' ? 'ls -1Ap' : `ls -1Ap ${shellQuote(absPath)}`
+      const res = await client.run(command)
+      if (!res.ok) return { ok: false, error: (res.stderr ?? '').trim() || res.error || '列出目录失败' }
+      const entries = res.stdout
+        .split('\n')
+        .filter((name) => name !== '')
+        .map((name) => ({ name: name.replace(/\/$/, ''), dir: name.endsWith('/') }))
+      return { ok: true, entries, path: absPath }
+    },
+
+    /**
+     * Open a remote directory as a workspace: create an EMPTY local anchor
+     * directory (the harness's workspace identity — `fs.realpath` must resolve
+     * it) and register it in the routing registry. The caller then adopts the
+     * anchor through `workspaceRegistry.create`; all file/command I/O routes
+     * to the remote. No mirroring, no sync.
+     */
+    async openRemoteWorkspace(machine, path) {
+      const client = sshClientFor(machine)
+      let sftp
+      try {
+        sftp = await client.sftp()
+      } catch (error) {
+        return { ok: false, error: `无法建立 SFTP 连接：${messageOf(error)}` }
+      }
+      try {
+        const rel = path === undefined || path === '' ? '.' : path
+        const remotePath = await sftp.realpath(rel)
+        const anchorPath = ensureAnchor(machine, remotePath)
+        registerAnchor({
+          anchorPath,
+          machineId: machine?.id,
+          host: machine?.host ?? null,
+          port: machine?.port ?? null,
+          user: machine?.user ?? null,
+          remotePath,
+        })
+        return { ok: true, localDir: anchorPath, remotePath }
+      } catch (error) {
+        return { ok: false, error: messageOf(error) }
+      } finally {
+        sftp.end()
+      }
+    },
+  }
+}
+
+export function apply(ctx) {
+  // Migrate any legacy plaintext secrets to the encrypted form once, at load.
+  try { ensureSecretsEncrypted() } catch { }
+
+  ctx.provide('sshClient', new SshClient())
+
+  // Routing providers. Their harness services are captured via inject
+  // (deferred until available) because the plugin's own `ctx.get` may not
+  // resolve root-scoped services directly.
+  const deps = { policy: undefined, sandbox: undefined, subprocess: undefined }
+  const remote = {
+    getPolicy: () => deps.policy,
+    getSandbox: () => deps.sandbox,
+    getSubprocess: () => deps.subprocess,
+    clientForRemote,
+  }
+  ctx.inject(['sandbox', 'subprocess', 'sandboxPolicy'], (sctx) => {
+    deps.policy = sctx.get('sandboxPolicy')
+    deps.sandbox = sctx.get('sandbox')
+    deps.subprocess = sctx.get('subprocess')
+    return () => { deps.policy = deps.sandbox = deps.subprocess = undefined }
+  })
+  ctx.provide('fs', new RoutingFileSystem(remote))
+  ctx.provide('shell', new SshShellExecutor(remote))
+
+  const service = remoteWorkspacesService()
+  service.typertRemote = Object.freeze({ service, serviceKey: NAMESPACE, namespace: NAMESPACE })
+  ctx.provide(NAMESPACE, service)
+
+  // Remote-aware grep/glob (replace the local ripgrep tool-fs-search), deferred
+  // until `tools` is available.
+  ctx.inject(['tools'], (toolsCtx) => {
+    applySearchTools(toolsCtx, remote)
+  })
+
+  // Shadow the harness's global `cwd` prompt variable per-agent so a remote
+  // workspace's persona line ("Your working directory is {{cwd}}") shows the
+  // REMOTE path instead of the empty local anchor. Local agents keep their cwd
+  // unchanged. Routing still uses `session.header.cwd` — this only rewrites the
+  // prompt text.
+  ctx.on('agent/created', ({ agent }) => {
+    agent.ctx.inject(['systemPrompt'], (scope) => {
+      scope.systemPrompt.variable('cwd', (context) => {
+        const cwd = context.agent?.session?.header?.cwd
+        if (typeof cwd !== 'string' || cwd === '') return cwd
+        const hit = findByCwd(cwd)
+        if (hit === undefined) return cwd
+        return hit.remoteSubpath === '' ? hit.remotePath : `${hit.remotePath.replace(/\/+$/, '')}/${hit.remoteSubpath}`
+      })
+    })
+  })
+
+  // Clarify remote workspaces to the model — only when the session's cwd is a
+  // registered remote anchor (empty text hides the section for local sessions).
+  ctx.inject(['systemPrompt'], (sctx) => {
+    const systemPrompt = sctx.get('systemPrompt')
+    if (systemPrompt === undefined) return
+    systemPrompt.section({
+      name: 'dsh-remote-workspaces:notice',
+      order: 10,
+      text: (context) => {
+        const cwd = context.agent?.session?.header?.cwd
+        if (typeof cwd !== 'string' || cwd === '') return ''
+        const hit = findByCwd(cwd)
+        if (hit === undefined) return ''
+        const host = hit.user ? `${hit.user}@${hit.host}` : hit.host
+        return `Remote workspace over SSH (${host}): file/search tools and shell commands run on the remote host; use relative paths (they route to the remote automatically).`
+      },
+    })
+  })
+
+  // The typert registry activates after this dependency-free plugin, so the
+  // strict Remote contribution is deferred until `typert` is available.
+  ctx.inject(['typert'], (typertCtx) => {
+    const typert = typertCtx.get('typert')
+    if (typert === undefined) return
+    return typert.register({
+      package: PACKAGE,
+      face: 'host',
+      schemas: [],
+      model: { services: [], events: [], objects: [] },
+      invocations: INVOCATIONS,
+    })
+  })
+}
+
+export default apply