dsh-ssh-workbench 1.6.4 → 1.7.8

package/lib/core/managed-context.js

@@ -0,0 +1,287 @@
+/**
+ * Per-turn managed-resource context.
+ *
+ * The composer inserts an `@name` chip as plain text. This module treats it as a
+ * hint, not an execution binding: every remote tool call names its own server.
+ * This module injects one compact inventory + tool-rules message per human
+ * turn, so the model never has to read `servers.json` or switch a hidden
+ * session target before acting.
+ *
+ * The message enters the same step (`agent/pre-step` replaces the messages that
+ * enter a step), which `agent.inject()` cannot promise because it splices into
+ * the next step.
+ *
+ * Scope: every agent mode; no preset gating.
+ */
+import { randomUUID } from 'node:crypto'
+
+import { effectiveDialect } from './dialect.js'
+import { loadServers } from './store.js'
+import {
+  TARGET_CONTEXT_KIND,
+  createTargetStore,
+  extractServerMentions,
+  extractUserText,
+  lastHumanMessage,
+} from './mentions.js'
+
+export { TARGET_CONTEXT_KIND }
+
+const DEFAULT_MAX_CONTEXT_SERVERS = 20
+
+function describeError(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function serverLine(server) {
+  const target = `${server.username ?? 'root'}@${server.host}:${server.port ?? 22}`
+  const state = server.enabled === false ? ' · disabled' : ''
+  const dialect = effectiveDialect(server)
+  return `- ${server.name} — ${target} · ${dialect}${state}${factsSummary(server)}`
+}
+
+/** Compact facts summary (hostname only: stable, not a stale capacity snapshot). */
+function factsSummary(server) {
+  const facts = server?.facts
+  if (!facts || typeof facts !== 'object') return ''
+  const hostname = typeof facts.hostname === 'string' ? facts.hostname.trim() : ''
+  return hostname ? ` · ${hostname}` : ''
+}
+
+function localShellName(hostPlatform) {
+  return hostPlatform === 'win32' ? 'pwsh' : 'bash'
+}
+
+/**
+ * Render the model-facing managed-resource context.
+ *
+ * @param {object[]} servers managed inventory
+ * @param {{
+ *   candidates?: string[],
+ *   lastExecuted?: string|null,
+ *   hostPlatform?: 'win32'|'posix',
+ *   maxServers?: number,
+ * }} [hints]
+ */
+export function renderManagedContext(servers, hints = {}) {
+  const inventory = Array.isArray(servers) ? servers.filter(Boolean) : []
+  if (inventory.length === 0) return ''
+  const maxServers = Number.isInteger(hints.maxServers) && hints.maxServers > 0
+    ? hints.maxServers
+    : DEFAULT_MAX_CONTEXT_SERVERS
+  const listed = inventory.slice(0, maxServers)
+  const lines = [`[ssh-workbench] Managed remote resources (${inventory.length}):`]
+  for (const server of listed) lines.push(serverLine(server))
+  if (inventory.length > listed.length) {
+    lines.push(`- … and ${inventory.length - listed.length} more; call remote_exec with a resource name from the workbench UI.`)
+  }
+  lines.push('Remote execution rules:')
+  lines.push(
+    `- The native ${localShellName(hints.hostPlatform)} tool always runs on the local DSH host. Never use it for commands meant for a remote resource.`,
+  )
+  lines.push(
+    '- POSIX resources: remote_bash({ server: "<name>", command: "<command>", workdir?, timeoutMs?, run_in_background? }).',
+  )
+  lines.push(
+    '- Windows resources: remote_pwsh({ server: "<name>", command: "<command>", ... }).',
+  )
+  lines.push(
+    '- Several resources in one step: remote_exec({ tasks: [{ server: "<name>", command: "<command>" }], concurrency? }). Tasks run concurrently and never depend on a remembered target.',
+  )
+  lines.push(
+    '- Pass server explicitly on every call. The resource names above are authoritative; never read ~/.dsh/ssh-workbench/servers.json or other config files to find them.',
+  )
+  lines.push(
+    '- read/write/edit/glob/grep are the native local file tools; they never touch a remote resource.',
+  )
+  lines.push(
+    '- Remote files: remote_read({ server, path, maxBytes? }), remote_glob({ server, pattern, path?, maxResults?, maxDepth? }) and remote_grep({ server, pattern, path?, ignoreCase?, maxResults? }). Use absolute paths or paths under ~.',
+  )
+  if (hints.remoteFileWrite === true) {
+    lines.push(
+      '- Remote writes are enabled: remote_write({ server, path, content }) and remote_edit({ server, path, oldText, newText, replaceAll? }). remote_edit requires one exact match unless replaceAll=true.',
+    )
+  } else {
+    lines.push(
+      '- Remote writes are disabled: remote_write/remote_edit will refuse. Use the workbench SFTP panel for uploads, or ask the user to turn on remote writes in the plugin settings.',
+    )
+  }
+  const candidates = Array.isArray(hints.candidates) ? hints.candidates.filter(Boolean) : []
+  if (candidates.length > 0) {
+    lines.push(
+      `- The user mentioned: ${candidates.join(', ')}. Prefer these resources when the request is ambiguous, but still pass server explicitly.`,
+    )
+  }
+  const lastExecuted = typeof hints.lastExecuted === 'string' && hints.lastExecuted.length > 0
+    ? hints.lastExecuted
+    : null
+  if (lastExecuted) lines.push(`- Last remote execution in this conversation: ${lastExecuted}.`)
+  lines.push(
+    '- If no resource is named and the request does not identify one, ask the user or use the resource named in the request; do not guess silently.',
+  )
+  return lines.join('\n')
+}
+
+/**
+ * Build one user-role context message, preferring the host's message factory.
+ * `@` symbols are avoided so this message can never be re-matched as a mention.
+ */
+export function buildManagedContextMessage(servers, hints, createUserMessage) {
+  const text = renderManagedContext(servers, hints)
+  const source = {
+    kind: TARGET_CONTEXT_KIND,
+    form: 'notice',
+    summary: 'managed remote resources',
+  }
+  const input = { content: [{ type: 'text', text }], source }
+  if (typeof createUserMessage === 'function') return createUserMessage(input)
+  return { role: 'user', id: `ssh-workbench-context-${randomUUID()}`, ...structuredClone(input) }
+}
+
+/**
+ * Install the resource-context provider.
+ *
+ * @param {object} ctx plugin context
+ * @param {{
+ *   enabled?: boolean,
+ *   remoteAvailable?: boolean,
+ *   hostPlatform?: 'win32'|'posix',
+ *   targets?: object,
+ *   loadInventory?: () => object[],
+ *   loadLastExecuted?: (sessionId: string) => string|null,
+ *   remoteFileWrite?: boolean,
+ *   loadRemoteFileWrite?: () => boolean,
+ *   createUserMessage?: Function,
+ * }} [options]
+ */
+export function installManagedContext(ctx, options = {}) {
+  const enabled = options.enabled !== false
+  const remoteAvailable = options.remoteAvailable !== false
+  const loadInventory = options.loadInventory ?? loadServers
+  const targets = options.targets ?? createTargetStore({ loadInventory })
+  const maxContextServers = Number.isInteger(options.maxContextServers) && options.maxContextServers > 0
+    ? options.maxContextServers
+    : DEFAULT_MAX_CONTEXT_SERVERS
+  const warn = (message) => {
+    try {
+      ctx?.logger?.warn?.(`dsh-ssh-workbench: ${message}`)
+    } catch {
+      // Logging must never fail the plugin.
+    }
+  }
+  if (!ctx || typeof ctx.on !== 'function') return { targets }
+
+  let factory = options.createUserMessage
+  const messageFactory = async () => {
+    if (factory !== undefined) return factory
+    try {
+      const mod = await import('@deepseek-ai/dsh-llm')
+      factory = typeof mod.createUserMessage === 'function' ? mod.createUserMessage : null
+    } catch {
+      factory = null
+    }
+    return factory
+  }
+
+  const handler = async (payload, next) => {
+    const decision = await next()
+    try {
+      if (!decision || decision.kind === 'reject' || payload?.signal?.aborted) return decision
+      if (enabled === false) return decision
+      // Never describe a remote world the Host cannot execute in.
+      if (!remoteAvailable) return decision
+      const agent = payload?.agent
+      const session = agent?.session
+      const key = session?.id ?? agent?.id
+      if (typeof key !== 'string' || key.length === 0) return decision
+      let servers
+      try {
+        servers = loadInventory()
+      } catch (error) {
+        warn(`inventory unavailable: ${describeError(error)}`)
+        return decision
+      }
+      if (!Array.isArray(servers) || servers.length === 0) return decision
+      // Restore resumed-Session mention hints once; deriveMessages() is
+      // intentionally skipped on later steps.
+      if (targets.get(key)?.seeded !== true) {
+        try {
+          const history = typeof session?.deriveMessages === 'function' ? session.deriveMessages() : []
+          targets.ensureSeeded(key, history, servers)
+        } catch {
+          targets.ensureSeeded(key, [], servers)
+        }
+      }
+      const human = lastHumanMessage(decision.messages)
+      const mentions = human ? extractServerMentions(extractUserText(human), servers) : []
+      const state = targets.bindMentions(key, mentions, human?.id)
+      if (!state) return decision
+      const changed = state.version !== state.injectedVersion
+      const firstStep = payload?.step === 1
+      if (!changed) {
+        if (!firstStep) return decision
+        // One context message per turn is enough while it is still present in
+        // the step messages. Re-inject after compaction or a new human turn.
+        const hasContext = decision.messages.some((message) => message?.source?.kind === TARGET_CONTEXT_KIND)
+        if (hasContext) return decision
+      }
+      let lastExecuted = null
+      try {
+        lastExecuted = typeof options.loadLastExecuted === 'function' ? options.loadLastExecuted(key) : null
+      } catch {
+        lastExecuted = null
+      }
+      let remoteFileWrite = options.remoteFileWrite === true
+      if (typeof options.loadRemoteFileWrite === 'function') {
+        try {
+          remoteFileWrite = options.loadRemoteFileWrite() === true
+        } catch {
+          remoteFileWrite = false
+        }
+      }
+      const hints = {
+        candidates: state.candidates,
+        lastExecuted: typeof lastExecuted === 'string' && lastExecuted.length > 0 ? lastExecuted : null,
+        hostPlatform: options.hostPlatform,
+        maxServers: maxContextServers,
+        remoteFileWrite,
+      }
+      const message = buildManagedContextMessage(servers, hints, await messageFactory())
+      targets.markInjected(key, state.version)
+      return { ...decision, messages: [...decision.messages, message] }
+    } catch (error) {
+      warn(`resource context skipped: ${describeError(error)}`)
+      return decision
+    }
+  }
+
+  const offPreStep = ctx.on('agent/pre-step', handler, { prepend: true })
+  const offDisposed = ctx.on('agent/disposed', (disposed) => {
+    try {
+      const session = disposed?.agent?.session
+      const key = session?.id ?? disposed?.agent?.id
+      if (typeof key === 'string') targets.clear(key)
+    } catch {
+      // Best effort cleanup.
+    }
+  })
+  if (typeof ctx.effect === 'function') {
+    ctx.effect(
+      () => () => {
+        try {
+          offPreStep?.()
+        } catch {
+          // Disposal is best effort.
+        }
+        try {
+          offDisposed?.()
+        } catch {
+          // Disposal is best effort.
+        }
+        targets.clearAll?.()
+      },
+      'dsh-ssh-workbench: resource context',
+    )
+  }
+  return { targets, offPreStep, offDisposed }
+}

package/lib/core/{targets.js → mentions.js}

@@ -1,26 +1,18 @@
 /**
- * Per-session remote target binding.
+ * Per-session resource hints for the composer and the injected context.
  *
- * A session owns at most one *active* target: the managed server its native
- * `bash` tool runs on. `@name` mentions in a human message are the primary
- * input; the `ssh_workbench_target` tool switches the active target explicitly so a
- * conversation that mentions several servers stays unambiguous.
- *
- * State is process-local and keyed by Session id. It is a derived cache, not a
- * source of truth: the durable input is the human messages in the Session log,
- * which `replayTargets()` folds back in when a Session resumes.
+ * Every remote tool call carries its own `server`, so this store only
+ * remembers which managed resources the human mentioned with `@name` in the
+ * current conversation. It is a hint for the model and the UI, never an
+ * execution binding. The durable input is still the Session log, which
+ * `replayTargets()` folds back in after a resume.
  */
 import { loadServers } from './store.js'
+import { findServerRef } from './server-ref.js'
 
-/** Tool name the model calls to switch targets. */
-export const TARGET_TOOL_NAME = 'ssh_workbench_target'
-
-/** Source kind recorded on the injected target-context message. */
+/** Source kind recorded on the injected resource-context message. */
 export const TARGET_CONTEXT_KIND = 'ssh-workbench-target'
 
-/** The sentinel that detaches the session from any remote target. */
-export const LOCAL_TARGET = 'local'
-
 /** Concatenate the text blocks of one message. */
 export function extractUserText(message) {
   if (!message || message.role !== 'user' || !Array.isArray(message.content)) return ''
@@ -85,52 +77,47 @@ function sameList(left, right) {
   return left.every((value, index) => value === right[index])
 }
 
+function mentionNames(mentions) {
+  const names = []
+  for (const server of Array.isArray(mentions) ? mentions : []) {
+    const name = typeof server?.name === 'string' ? server.name : ''
+    if (name && !names.includes(name)) names.push(name)
+  }
+  return names
+}
+
 function freshState() {
-  return { candidates: [], active: null, version: 0, injectedVersion: -1, notifiedVersion: -1, seeded: false }
+  return { candidates: [], lastHumanId: null, version: 0, injectedVersion: -1, seeded: false }
 }
 
-/**
- * Fold the mention rules over one session state.
- *
- * - one mention       → that server becomes the active target;
- * - several mentions  → candidates are remembered, active target is cleared;
- * - no mention        → state is unchanged (a follow-up keeps its target).
- */
+/** Remember the latest @mentions. No target is selected or cleared. */
 export function applyMentions(state, mentions) {
-  if (!Array.isArray(mentions) || mentions.length === 0) return state
-  const names = mentions.map((server) => server.name)
-  if (mentions.length === 1) {
-    if (state.active === names[0] && sameList(state.candidates, names)) return state
-    return { ...state, candidates: names, active: names[0], version: state.version + 1 }
-  }
-  // Several mentions never pick a target by guesswork; the model must call the
-  // selector tool. The previous active target is dropped for the same reason.
-  const active = null
-  if (active === state.active && sameList(state.candidates, names)) return state
-  return { ...state, candidates: names, active, version: state.version + 1 }
+  const names = mentionNames(mentions)
+  if (names.length === 0) return state
+  if (sameList(state.candidates, names)) return state
+  return { ...state, candidates: names, version: state.version + 1 }
 }
 
-/** Replay the mention rules over a Session's historical messages. */
+/** Replay the mention hints over a Session's historical messages. */
 export function replayTargets(messages, servers) {
   let state = freshState()
   if (Array.isArray(messages)) {
     for (const message of messages) {
       if (message?.role !== 'user' || message.source?.kind !== 'user') continue
-      state = applyMentions(state, extractServerMentions(extractUserText(message), servers))
+      const mentions = extractServerMentions(extractUserText(message), servers)
+      if (mentions.length > 0) state = applyMentions(state, mentions)
     }
   }
   return state
 }
 
-/** Resolve one target reference against the inventory (name or id). */
+/** Resolve one resource reference against the inventory (name or id). */
 export function findTarget(servers, ref) {
-  const value = String(ref ?? '').trim()
-  if (!value) return undefined
-  return servers.find((server) => server.id === value || server.name === value)
+  return findServerRef(servers, ref)
 }
 
 /**
- * Create the per-session target store.
+ * Create the per-session resource-hint store.
  * @param {{ loadInventory?: () => object[] }} [options]
  */
 export function createTargetStore(options = {}) {
@@ -167,52 +154,42 @@ export function createTargetStore(options = {}) {
     const state = ensure(key)
     if (state === undefined || state.seeded) return state
     const replayed = replayTargets(messages, servers)
+    const history = Array.isArray(messages) ? messages : []
+    const lastHuman = [...history].reverse().find(
+      (message) => message?.role === 'user' && message.source?.kind === 'user',
+    )
     const next = {
       ...state,
       candidates: replayed.candidates,
-      active: replayed.active,
-      version: replayed.version,
+      lastHumanId: typeof lastHuman?.id === 'string' ? lastHuman.id : state.lastHumanId,
+      version: replayed.candidates.length > 0 ? 1 : 0,
       seeded: true,
     }
     sessions.set(sessionKey(key), next)
     return next
   }
 
-  function bindMentions(key, mentions) {
+  /**
+   * Fold one human message into the hint state.
+   * A new human message always bumps `version` so the per-turn resource
+   * context is injected even when the message contains no @mention.
+   */
+  function bindMentions(key, mentions, humanId) {
     const state = ensure(key)
     if (state === undefined) return undefined
-    const next = { ...applyMentions(state, mentions), seeded: true }
-    if (next !== state) sessions.set(sessionKey(key), next)
-    return next
-  }
-
-  /** Switch the active target explicitly. `local` detaches. */
-  function setActive(key, ref, servers = loadInventory()) {
-    const state = ensure(key)
-    if (state === undefined) return { ok: false, error: 'session is not addressable' }
-    if (String(ref).trim().toLowerCase() === LOCAL_TARGET) {
-      // Detaching also clears any pending @a @b ambiguity, so bash is plainly
-      // local again instead of staying blocked on "choose a target".
-      const next = { ...state, active: null, candidates: [], version: state.version + 1, seeded: true }
-      sessions.set(sessionKey(key), next)
-      return { ok: true, state: next }
-    }
-    const server = findTarget(servers, ref)
-    if (server === undefined) {
-      return { ok: false, error: `unknown server "${String(ref)}"`, state }
-    }
-    if (server.enabled === false) {
-      return { ok: false, error: `server "${server.name}" is disabled`, state }
-    }
+    const newHuman = typeof humanId === 'string' && humanId.length > 0 && humanId !== state.lastHumanId
+    const names = mentionNames(mentions)
+    const changedMentions = names.length > 0 && !sameList(state.candidates, names)
+    if (!newHuman && !changedMentions) return state
     const next = {
       ...state,
-      active: server.name,
-      candidates: state.candidates.includes(server.name) ? state.candidates : [server.name],
+      candidates: names.length > 0 ? names : state.candidates,
+      lastHumanId: typeof humanId === 'string' && humanId.length > 0 ? humanId : state.lastHumanId,
       version: state.version + 1,
       seeded: true,
     }
     sessions.set(sessionKey(key), next)
-    return { ok: true, state: next, server }
+    return next
   }
 
   function markInjected(key, version) {
@@ -222,17 +199,6 @@ export function createTargetStore(options = {}) {
     sessions.set(sessionKey(key), { ...state, injectedVersion: version })
   }
 
-  /**
-   * Remember that the bash router already showed the target to the model/UI
-   * (one stderr line after each target change), so it is not repeated per call.
-   */
-  function markNotified(key, version) {
-    const state = get(key)
-    if (state === undefined) return
-    if (state.notifiedVersion === version) return
-    sessions.set(sessionKey(key), { ...state, notifiedVersion: version })
-  }
-
   function clear(key) {
     const sessionId = sessionKey(key)
     if (sessionId !== undefined) sessions.delete(sessionId)
@@ -246,5 +212,5 @@ export function createTargetStore(options = {}) {
     return sessions.size
   }
 
-  return { get, ensure, ensureSeeded, bindMentions, setActive, markInjected, markNotified, clear, clearAll, size, loadInventory }
+  return { get, ensure, ensureSeeded, bindMentions, markInjected, clear, clearAll, size, loadInventory }
 }

package/lib/core/posix-shell.js

@@ -0,0 +1,89 @@
+/**
+ * Shared POSIX remote-shell helpers.
+ *
+ * Pure command construction used by `remote_bash` and `remote_exec`; the
+ * native local `bash` tool never reaches this module.
+ */
+import { quotePosix } from './posix-quote.js'
+
+const MIN_TIMEOUT_MS = 1000
+
+/**
+ * Wrap a remote command with the remote `timeout` utility.
+ *
+ * A client-side timeout only closes the SSH channel; a process that ignores
+ * SIGHUP (nohup/background) keeps running on the server. Wrapping the command
+ * gives the remote side the same deadline: coreutils `timeout` runs the
+ * managed command in its own process group and signals the whole group, so
+ * when the client gives up the remote work stops too. `kill` adds `-k <n>`
+ * (KILL after TERM); `basic` sends TERM only; `none` (or an unknown
+ * capability) leaves the command untouched.
+ *
+ * The wrapper re-enters the remote login shell (`<shell> -c`) so shell
+ * semantics do not change. The shell path comes from the capability probe and
+ * is referenced as a quoted literal, so this also works on fish/csh (no POSIX
+ * `${SHELL:-...}` expansion). The command itself is single-quote escaped and
+ * therefore expanded exactly once, inside that shell.
+ *
+ * @param {string} command
+ * @param {number} timeoutMs
+ * @param {'kill'|'basic'|'none'|{mode?: string, shell?: string}} [capability]
+ * @param {{ killAfterMs?: number }} [options]
+ */
+export function wrapRemoteTimeout(command, timeoutMs, capability = 'none', options = {}) {
+  const info = typeof capability === 'string' ? { mode: capability } : (capability ?? {})
+  const mode = info.mode === 'kill' || info.mode === 'basic' ? info.mode : 'none'
+  if (mode === 'none') return String(command ?? '')
+  const shell = typeof info.shell === 'string' && info.shell.startsWith('/') ? info.shell : '/bin/sh'
+  const killAfterMs = Number.isFinite(options.killAfterMs) ? options.killAfterMs : 5000
+  const killSeconds = Math.max(0, Math.ceil(killAfterMs / 1000))
+  const seconds = Math.max(1, Number(timeoutMs) / 1000)
+  const suffix = mode === 'kill' && killSeconds > 0 ? `-k ${killSeconds} ` : ''
+  return `timeout ${suffix}${seconds} ${quotePosix(shell)} -c ${quotePosix(command)}`
+}
+
+/**
+ * Turn the model-facing `workdir` into a shell prefix and the value's cwd label.
+ *
+ * The remote shell starts in the login home; absolute paths are used verbatim,
+ * `~`/`~/x` and relative paths are anchored at `$HOME`.
+ *
+ * @returns {{ command: string, cwd: string } | { error: string }}
+ */
+export function applyWorkdir(command, workdir) {
+  const raw = typeof workdir === 'string' ? workdir.trim() : ''
+  const body = String(command ?? '')
+  if (!raw) return { command: body, cwd: '~' }
+  if (raw.includes('\n') || raw.includes('\r')) return { error: 'workdir must not contain newlines' }
+  if (raw.startsWith('~')) {
+    const rest = raw === '~' ? '' : raw.slice(1)
+    if (rest !== '' && !rest.startsWith('/')) return { error: 'workdir must be an absolute path, ~/path, or a relative path' }
+    const target = rest === '' ? '"$HOME"' : `"$HOME"${quotePosix(rest)}`
+    return { command: `cd -- ${target} && ${body}`, cwd: raw }
+  }
+  if (raw.startsWith('/')) {
+    return { command: `cd -- ${quotePosix(raw)} && ${body}`, cwd: raw }
+  }
+  return { command: `cd -- "$HOME"/${quotePosix(raw)} && ${body}`, cwd: `~/${raw}` }
+}
+
+/** Effective timeout for one call, clamped to the configured ceiling. */
+export function resolveTimeoutMs(args, config) {
+  const ceiling = Number.isInteger(config?.maxCommandTimeoutMs) ? config.maxCommandTimeoutMs : 30 * 60 * 1000
+  const requested = Number.isInteger(args?.timeoutMs) ? args.timeoutMs : undefined
+  const fallback = Number.isInteger(config?.commandTimeoutMs) ? config.commandTimeoutMs : 120000
+  const value = requested ?? fallback
+  return Math.max(MIN_TIMEOUT_MS, Math.min(value, ceiling))
+}
+
+/**
+ * Whether a runtime result means the command never reached the remote shell.
+ * Timeouts and aborts are real command outcomes (timedOut / aborted on the
+ * native value), not transport failures.
+ */
+export function isTransportFailure(result) {
+  if (!result || typeof result !== 'object') return true
+  if (result.exitCode !== null && result.exitCode !== undefined) return false
+  if (typeof result.signal === 'string' && result.signal.length > 0) return false
+  return result.outcome === 'failed'
+}

package/lib/core/prefs.js

@@ -2,18 +2,25 @@
  * Small user-visible UI preferences that are not part of the server inventory.
  *
  * Kept in the same private data directory as the inventory so a profile export
- * carries them, and so the plugin manager's sidebar switch can change them
+ * carries them, and so the plugin manager's settings form can change them
  * without rewriting the profile's cordis.patch.yml.
+ *
+ * `remoteFileWrite` is deliberately tri-state: `null` means "follow the plugin
+ * config", a boolean means the user overrode it from the settings UI. Keeping
+ * the override separate from the config lets the plugin detail page show a
+ * switch without making the config file the only way in.
  */
 import { prefsPath, readTextFile, writePrivateFile } from './paths.js'
 
-export const DEFAULT_PREFS = Object.freeze({ sidebar: true })
+export const DEFAULT_PREFS = Object.freeze({ sidebar: true, remoteFileWrite: null, systemFileHierarchy: null })
 
 /** Coerce a stored document into the current preference shape. */
-export function normalizePrefs(raw) {
+function normalizePrefs(raw) {
   const prefs = { ...DEFAULT_PREFS }
   if (!raw || typeof raw !== 'object') return prefs
   if (typeof raw.sidebar === 'boolean') prefs.sidebar = raw.sidebar
+  if (typeof raw.remoteFileWrite === 'boolean') prefs.remoteFileWrite = raw.remoteFileWrite
+  if (typeof raw.systemFileHierarchy === 'boolean') prefs.systemFileHierarchy = raw.systemFileHierarchy
   return prefs
 }
 
@@ -36,3 +43,29 @@ export function savePrefs(patch) {
   writePrivateFile(prefsPath(), `${JSON.stringify(next, null, 2)}\n`)
   return next
 }
+
+/**
+ * Resolve the write switch the tools and the model context should honour.
+ *
+ * A stored override wins; otherwise the plugin config decides. Anything that
+ * is neither `true` nor `false` falls back to the config, so a corrupt prefs
+ * file can never silently enable remote writes.
+ */
+export function resolveRemoteFileWrite(config, prefs) {
+  const override = prefs?.remoteFileWrite
+  if (override === true || override === false) return override
+  return config?.remoteFileWrite === true
+}
+
+/**
+ * Resolve the hierarchical system file browser switch.
+ *
+ * Same tri-state contract as the write switch: a settings-page override wins,
+ * otherwise the plugin config decides. Defaults to off so the native files tab
+ * is untouched unless the user explicitly asks for the hierarchical browser.
+ */
+export function resolveSystemFileHierarchy(config, prefs) {
+  const override = prefs?.systemFileHierarchy
+  if (override === true || override === false) return override
+  return config?.systemFileHierarchy === true
+}