dsh-mcp-panel 0.2.0

package/src/index.ts

@@ -0,0 +1,86 @@
+/**
+ * `dsh-mcp-panel` — read-only runtime management panel for the official
+ * DeepSeek Harness MCP client (`@deepseek-ai/dsh-mcp-client`).
+ *
+ * Host half: mounts the `mcpPanel` Remote service (loader rows + tool
+ * registry + upstream `mcp/status` observations), registers the `/mcp`
+ * command where a command registry exists, and optionally registers the
+ * `mcp_probe` background-job tool where a job registry exists. The panel
+ * never edits configuration files and never fabricates connection state:
+ * without the proposed upstream status seam every connection field reads
+ * `unknown` with `statusSource: 'derived'`.
+ *
+ * Function plugin — no default export (the Loader unwraps
+ * `exports.default ?? exports`).
+ *
+ * @module dsh-mcp-panel
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-commands'
+import type {} from '@deepseek-ai/dsh-tools'
+import type {} from '@deepseek-ai/dsh-jobs'
+import { Config, resolveConfig } from './config.ts'
+import { mcpCommand } from './command.ts'
+import { mcpProbeTool } from './probe.ts'
+import { McpPanelService } from './service.ts'
+import { MCP_STATUS_EVENT, type McpStatusQuery } from './upstream.ts'
+
+export const name = 'mcp-panel'
+
+/** Hard services: the facts the panel reads. `commands`/`jobs` are optional children. */
+export const inject = ['tools', 'loader']
+
+export { Config, resolveConfig } from './config.ts'
+export { McpPanelService } from './service.ts'
+export { mcpCommand, parseMcpArgs, renderList, renderPatchSuggestion, renderServer, renderTools } from './command.ts'
+export { groupMcpTools, countServerTools } from './grouping.ts'
+export { aggregateServerView, aggregateSnapshot, deriveTarget, serverNameOf } from './aggregate.ts'
+export { sanitizeError, sanitizeText, sanitizeUrl } from './sanitize.ts'
+export { probeEndpoint, probeJob, mcpProbeTool } from './probe.ts'
+export { MCP_STATUS_EVENT, type McpStatusPayload, type McpStatusQuery, type McpServerStatus } from './upstream.ts'
+export type * from './wire.ts'
+
+/**
+ * Mount the panel: the snapshot service, the upstream status seam consumer,
+ * the `/mcp` command (when commands exist), and the probe tool (when enabled
+ * and a job registry exists).
+ *
+ * @param ctx - context carrying tools + loader.
+ * @param config - raw loader config; defaults applied through {@link resolveConfig}.
+ */
+export async function apply(ctx: Context, config: Config): Promise<void> {
+  const resolved = resolveConfig(config)
+
+  // The service has injects, so its fiber activates asynchronously — await it
+  // before reading the instance the command and probe closures capture.
+  await ctx.plugin(McpPanelService, {
+    probeTimeoutMs: resolved.probeTimeoutMs,
+    maxProbes: resolved.maxProbes,
+    refreshIntervalMs: resolved.refreshIntervalMs,
+    passiveProbeEnabled: resolved.passiveProbeEnabled,
+    passiveProbeIntervalMs: resolved.passiveProbeIntervalMs,
+  })
+  const service = ctx.get('mcpPanel') as McpPanelService
+
+  // Consume the proposed upstream seam: live events plus a one-shot query
+  // seed from the (optional) status service when it is already mounted.
+  ctx.on(MCP_STATUS_EVENT, (payload) => { service.observe(payload) })
+  const query = ctx.get('mcpStatus') as McpStatusQuery | undefined
+  if (query !== undefined) {
+    for (const status of query.list()) service.observe(status)
+  }
+
+  // The /mcp command: only where a human-command registry is composed.
+  ctx.inject(['commands'], (scope) => {
+    scope.effect(() => scope.commands.register(mcpCommand(service, resolved.outputLanguage)), 'dsh-mcp-panel: /mcp command')
+  })
+
+  // The jobs controller serves the panel probe action AND the optional tool.
+  ctx.inject(['jobs'], (scope) => {
+    scope.effect(() => scope.jobs.attachController('dsh-mcp-panel'), 'dsh-mcp-panel: jobs controller')
+    if (resolved.probeEnabled) {
+      scope.effect(() => scope.tools.register(mcpProbeTool(service, scope.jobs, resolved.probeTimeoutMs)), 'dsh-mcp-panel: probe tool')
+    }
+  })
+}

package/src/probe.ts

@@ -0,0 +1,198 @@
+/**
+ * The optional `mcp_probe` tool: a one-shot connectivity probe of one
+ * configured Streamable HTTP endpoint, executed as an UNOWNED background job.
+ * Probe results are panel-only — the tool returns just the job id and a
+ * pointer to the settings tab, the job carries no owner (so no completion
+ * notice is injected into the model), and the panel reads the sanitized
+ * snapshot back through `mcpPanel/status`.
+ *
+ * @module dsh-mcp-panel/probe
+ */
+
+import type { JobHooks, JobOutcome, JobRegistry } from '@deepseek-ai/dsh-jobs'
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { sanitizeError, sanitizeText } from './sanitize.ts'
+import type { McpPanelService } from './service.ts'
+
+/** Producer kind; also the job-id prefix. */
+export const PROBE_KIND = 'mcp-probe'
+
+declare module '@deepseek-ai/dsh-jobs' {
+  interface JobKindMap {
+    /** One-shot Streamable HTTP connectivity probe (panel-only results). */
+    'mcp-probe': 'mcp-probe'
+  }
+}
+
+/** JSON-RPC MCP initialize request used by the probe (protocol constant). */
+const INITIALIZE_PROTOCOL_VERSION = '2024-11-05'
+
+/** MCP clientInfo facts; protocol constants, not configuration. Exported so the
+ * version-consistency tripwire (`tests/version.spec.ts`) can assert the
+ * advertised version tracks the package version. */
+export const PROBE_CLIENT_INFO = { name: 'dsh-mcp-panel', version: '0.2.0' }
+
+/** One settled probe: outcome status plus a sanitized one-line detail. */
+export interface ProbeOutcome {
+  /** How the job ended. */
+  status: 'completed' | 'failed'
+  /** Sanitized one-line detail (HTTP status, latency, server info, or error). */
+  detail: string
+}
+
+/** Display cap for server-reported name/version fields in probe details. */
+const DISPLAY_LIMIT = 80
+
+/** Bound one display string so hostile server metadata cannot blow up layouts. */
+function boundedDisplay(value: string): string {
+  return value.length <= DISPLAY_LIMIT ? value : `${value.slice(0, DISPLAY_LIMIT - 1)}…`
+}
+
+/**
+ * POST one MCP `initialize` request and describe the outcome in one sanitized
+ * line. Never sends or echoes credentials: the configured headers are used
+ * for the request itself (exactly as the bridge would) and never rendered.
+ *
+ * @param url - endpoint URL (already parsed by the caller).
+ * @param headers - the configured request headers; used, never displayed.
+ * @param timeoutMs - probe deadline.
+ * @param signal - caller-owned abort (job kill or timeout).
+ * @returns the settled probe outcome.
+ */
+export async function probeEndpoint(
+  url: string,
+  headers: Readonly<Record<string, string>>,
+  timeoutMs: number,
+  signal: AbortSignal,
+): Promise<ProbeOutcome> {
+  const started = Date.now()
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        accept: 'application/json, text/event-stream',
+        ...headers,
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: INITIALIZE_PROTOCOL_VERSION,
+          capabilities: {},
+          clientInfo: PROBE_CLIENT_INFO,
+        },
+      }),
+      signal,
+    })
+    const ms = Date.now() - started
+    if (!response.ok) {
+      return { status: 'failed', detail: `HTTP ${response.status} ${response.statusText} (${ms}ms)` }
+    }
+    let serverInfo: { name?: unknown; version?: unknown } = {}
+    try {
+      const body = (await response.json()) as { result?: { serverInfo?: { name?: unknown; version?: unknown } } }
+      serverInfo = body?.result?.serverInfo ?? {}
+    } catch {
+      // A 2xx without a JSON body: connectivity itself succeeded.
+    }
+    const name = typeof serverInfo.name === 'string' && serverInfo.name !== ''
+      ? boundedDisplay(sanitizeText(serverInfo.name))
+      : 'unnamed'
+    const version = typeof serverInfo.version === 'string' && serverInfo.version !== ''
+      ? boundedDisplay(sanitizeText(serverInfo.version))
+      : 'unknown version'
+    return { status: 'completed', detail: `HTTP ${response.status}, MCP initialize ok (server ${name} ${version}) in ${ms}ms` }
+  } catch (error) {
+    if (signal.aborted) return { status: 'failed', detail: `timeout after ${timeoutMs}ms or cancelled` }
+    return { status: 'failed', detail: sanitizeError(error) }
+  }
+}
+
+/**
+ * Create the background-job hooks for one probe: cancel aborts the fetch, the
+ * outcome settles `done` with sanitized detail only.
+ *
+ * @param url - endpoint URL.
+ * @param headers - configured headers (used, never rendered).
+ * @param timeoutMs - probe deadline.
+ * @returns the registry hooks.
+ */
+export function probeJob(url: string, headers: Readonly<Record<string, string>>, timeoutMs: number): JobHooks {
+  const controller = new AbortController()
+  const timer = setTimeout(() => { controller.abort() }, timeoutMs)
+  timer.unref?.()
+  const done: Promise<JobOutcome> = probeEndpoint(url, headers, timeoutMs, controller.signal)
+    .then(outcome => ({ ...outcome }))
+    .finally(() => { clearTimeout(timer) })
+  return {
+    cancel: () => { controller.abort() },
+    done,
+  }
+}
+
+/** Resolve one configured server's raw endpoint for probing. */
+function probeTarget(
+  service: McpPanelService,
+  server: string,
+): { url: string; headers: Record<string, string> } | undefined {
+  return service.rawEndpoint(server)
+}
+
+/**
+ * Build the `mcp_probe` tool definition.
+ *
+ * @param service - panel service (server lookup + snapshot for panel display).
+ * @param jobs - background-job registry the probe runs on.
+ * @param timeoutMs - per-probe deadline.
+ * @returns the registration-ready definition.
+ */
+export function mcpProbeTool(service: McpPanelService, jobs: JobRegistry, timeoutMs: number): ToolDefinition {
+  return defineTool({
+    name: 'mcp_probe',
+    description: 'Run a one-shot connectivity probe of a configured streamable-http MCP server as a background job. '
+      + 'Results appear in the MCP settings panel only — they are not injected into model context.',
+    parameters: {
+      server: {
+        type: 'string',
+        required: true,
+        description: 'serverName of a configured streamable-http MCP server (see /mcp for the list).',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          jobId: { type: 'string', required: true },
+          note: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: `Probe started (background job ${value.jobId}). Read the result in the MCP panel: Settings → Plugins → MCP.`,
+      }],
+    },
+    async execute(args) {
+      const target = probeTarget(service, args.server)
+      if (target === undefined) {
+        throw new Error(
+          `mcp_probe: "${args.server}" is not a configured streamable-http MCP server (see /mcp). `
+          + 'stdio servers have no HTTP endpoint to probe.',
+        )
+      }
+      const jobId = jobs.start({
+        kind: PROBE_KIND,
+        label: `mcp_probe ${args.server}`,
+        // Unowned: no model completion notice, readable by the panel only.
+        run: () => probeJob(target.url, target.headers, timeoutMs),
+      })
+      return {
+        jobId,
+        note: 'Probe results are panel-only: Settings → Plugins → MCP.',
+      }
+    },
+  })
+}

package/src/sanitize.ts

@@ -0,0 +1,115 @@
+/**
+ * Display sanitization for MCP panel surfaces. Everything the panel shows —
+ * the `/mcp` command output, the web settings tab, probe job details — passes
+ * through these pure functions so URL query-string credentials, userinfo
+ * passwords, header values, and bearer tokens never reach a display.
+ *
+ * The panel never shows configured `headers` at all (they are dropped at
+ * snapshot assembly); this module redacts what can still leak through target
+ * URLs and error text.
+ *
+ * @module dsh-mcp-panel/sanitize
+ */
+
+/** Replacement for every redacted credential value. */
+export const REDACTED = '***'
+
+/** Query/field keys whose values are credentials regardless of their name casing. */
+const CREDENTIAL_KEY = /^(?:access[_-]?token|api[_-]?key|apikey|auth|authorization|client[_-]?secret|key|password|passwd|pwd|secret|sig|signature|token)$/iu
+
+/** Credential keys for the unparseable-URL fallback and embedded-text scans. */
+const CREDENTIAL_KEY_SOURCE = '(?:access[_-]?token|api[_-]?key|apikey|auth(?:orization)?|client[_-]?secret|key|passw(?:or)?d|passwd|pwd|secret|sig(?:nature)?|token)'
+
+/** Whole userinfo before `@` (unparseable URLs only — parsed URLs redact just the password). */
+const USERINFO = /([a-z][a-z0-9+.-]*:\/\/)([^/@\s]+)@/giu
+
+/** `?key=value` / `&key=value` credential pairs inside arbitrary text. */
+const QUERY_CREDENTIAL = new RegExp(`([?&](?:[^=&#\\s]*${CREDENTIAL_KEY_SOURCE}[^=&#\\s]*)=)[^&#\\s]*`, 'giu')
+
+/** `#key=value` credential pairs in URL fragments and arbitrary text. */
+const FRAGMENT_CREDENTIAL = new RegExp(`(#[^=&#\\s]*${CREDENTIAL_KEY_SOURCE}[^=&#\\s]*=)[^&#\\s]*`, 'giu')
+
+/** `Authorization: <value>`-style header lines in arbitrary text (quoted value first). */
+const HEADER_CREDENTIAL_QUOTED = new RegExp(`(\\b${CREDENTIAL_KEY_SOURCE}\\s*[:=]\\s*["'])[^"']*(["'])`, 'giu')
+
+/** `Authorization: <value>`-style header lines with unquoted values. */
+const HEADER_CREDENTIAL_BARE = new RegExp(`(\\b${CREDENTIAL_KEY_SOURCE}\\s*[:=]\\s*)[^\\s,;)\\]}]+`, 'giu')
+
+/** Environment-variable-shaped credentials (`GITHUB_TOKEN=…`) in spawn errors. */
+const ENV_VAR_CREDENTIAL = /\b[A-Za-z0-9_]*(?:TOKEN|API[_-]?KEY|SECRET|PASSWORD|PASSWD)[A-Za-z0-9_]*\s*=\s*[^\s,;)\]}]+/gu
+
+/** Bearer tokens, including the `Bearer ` keyword and the token itself. */
+const BEARER = /(bearer)\s+[A-Za-z0-9._~+/=-]+/giu
+
+/** Quoted JSON-ish `"token": "value"` pairs in arbitrary text. */
+const QUOTED_CREDENTIAL = new RegExp(`(["'](?:access[_-]?token|api[_-]?key|client[_-]?secret|secret|token)["']\\s*[:=]\\s*["'])[^"']*(["'])`, 'giu')
+
+/** Raw JWT bodies, wherever they appear. */
+const JWT = /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}\b/gu
+
+/**
+ * Redact a URL for display: userinfo password, credential query values, and
+ * credential fragment pairs. Query keys are read through `URLSearchParams`,
+ * so percent-encoded key names are decoded before matching. Unparseable
+ * inputs fall back to pattern redaction (whole userinfo, credential query
+ * pairs, credential fragment pairs) instead of throwing.
+ *
+ * @param url - candidate URL text.
+ * @returns display-safe URL text.
+ */
+export function sanitizeUrl(url: string): string {
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    return url
+      .replace(USERINFO, '$1***@')
+      .replace(QUERY_CREDENTIAL, `$1${REDACTED}`)
+      .replace(FRAGMENT_CREDENTIAL, `$1${REDACTED}`)
+  }
+  if (parsed.password !== '') parsed.password = REDACTED
+  for (const key of [...parsed.searchParams.keys()]) {
+    if (CREDENTIAL_KEY.test(key)) parsed.searchParams.set(key, REDACTED)
+  }
+  if (parsed.hash !== '') parsed.hash = parsed.hash.replace(FRAGMENT_CREDENTIAL, `$1${REDACTED}`)
+  return parsed.toString()
+}
+
+/**
+ * Redact credential-shaped fragments from free text: header lines, bearer
+ * tokens, raw JWTs, embedded query pairs, and quoted token values.
+ *
+ * @param text - candidate display text.
+ * @returns display-safe text.
+ */
+export function sanitizeText(text: string): string {
+  return text
+    .replace(BEARER, `$1 ${REDACTED}`)
+    .replace(HEADER_CREDENTIAL_QUOTED, `$1${REDACTED}$2`)
+    .replace(HEADER_CREDENTIAL_BARE, `$1${REDACTED}`)
+    .replace(ENV_VAR_CREDENTIAL, value => {
+      const equals = value.indexOf('=')
+      return equals < 0 ? value : `${value.slice(0, equals)}=${REDACTED}`
+    })
+    .replace(QUOTED_CREDENTIAL, `$1${REDACTED}$2`)
+    .replace(QUERY_CREDENTIAL, `$1${REDACTED}`)
+    .replace(FRAGMENT_CREDENTIAL, `$1${REDACTED}`)
+    .replace(JWT, REDACTED)
+}
+
+/**
+ * Stringify an arbitrary thrown value safely and redact it for display.
+ * Never throws: unrenderable values degrade to a fixed marker.
+ *
+ * @param error - thrown value from a connection attempt, probe, or sync.
+ * @returns display-safe error text.
+ */
+export function sanitizeError(error: unknown): string {
+  let text: string
+  try {
+    text = typeof error === 'string' ? error : String(error)
+  } catch {
+    text = '<unrenderable error>'
+  }
+  return sanitizeText(text)
+}

package/src/service.ts

@@ -0,0 +1,279 @@
+/**
+ * The panel's host service: assembles the read-only MCP snapshot and serves
+ * it under the `mcpPanel` Typert Remote namespace (`mcpPanel/status`).
+ *
+ * Data sources, all read-only:
+ * - `ctx.loader` — mcp-client rows (raw config, effective disabled, fiber phase).
+ * - `ctx.tools.schemas()` — registered `mcp__<server>__` tool names + descriptions.
+ * - the proposed upstream `mcp/status` seam — observed via {@link observe}.
+ * - `ctx.jobs` — unowned `mcp-probe` background jobs (panel-only results).
+ *
+ * Connection status is reported honestly: without upstream observations the
+ * view reads `unknown` with `statusSource: 'derived'`; the panel never infers
+ * a connection state from tool-registry presence.
+ *
+ * @module dsh-mcp-panel/service
+ */
+
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Context } from '@deepseek-ai/cordis'
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
+import type {} from '@deepseek-ai/cordis-plugin-loader'
+// Type-only: activates the `ctx.jobs` Context merge.
+import type {} from '@deepseek-ai/dsh-jobs'
+// Type-only: activates the `mcp-probe` JobKindMap extension.
+import type {} from './probe.ts'
+import {
+  aggregateSnapshot,
+  MCP_CLIENT_MODULE,
+  serverNameOf,
+  type McpLoaderRow,
+} from './aggregate.ts'
+import { groupMcpTools } from './grouping.ts'
+import { probeEndpoint, probeJob, PROBE_KIND } from './probe.ts'
+import { sanitizeText } from './sanitize.ts'
+import type { McpServerStatus } from './upstream.ts'
+import type { McpFiberPhase, McpPanelSnapshot, McpProbeView, ProbeStarted } from './wire.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** Read-only MCP management snapshot service (this package). */
+    mcpPanel: McpPanelService
+  }
+}
+
+/**
+ * Runtime mirror of the Cordis `FiberState` const enum (numeric cross-package
+ * const enums have no runtime import), projected to the wire phases.
+ */
+const FIBER_PHASE: Record<number, McpFiberPhase> = {
+  0: 'pending',
+  1: 'loading',
+  2: 'active',
+  3: 'failed',
+  4: null,
+  5: 'unloading',
+}
+
+/** The profile patch-layer filename the enable/disable suggestions name. */
+const PROFILE_PATCH_FILENAME = 'cordis.patch.yml'
+
+/** Label prefix written by the `mcp_probe` tool and the panel probe action. */
+const PROBE_LABEL_PREFIX = 'mcp_probe '
+
+/** Service-level runtime settings; the plugin passes its resolved config in. */
+export interface McpPanelServiceConfig {
+  /** Per-probe timeout in milliseconds. */
+  probeTimeoutMs: number
+  /** Cap on probe records shown in the panel. */
+  maxProbes: number
+  /** Suggested panel refresh interval in ms (0 = on demand). */
+  refreshIntervalMs: number
+  /** Whether the passive probe loop runs. */
+  passiveProbeEnabled: boolean
+  /** Passive probe interval in milliseconds. */
+  passiveProbeIntervalMs: number
+}
+
+/** Defaults for direct (non-Loader) service construction. */
+const DEFAULT_SERVICE_CONFIG: McpPanelServiceConfig = {
+  probeTimeoutMs: 10_000,
+  maxProbes: 10,
+  refreshIntervalMs: 0,
+  passiveProbeEnabled: false,
+  passiveProbeIntervalMs: 60_000,
+}
+
+/** Read-only MCP management snapshot service, exported over the `mcpPanel` Remote namespace. */
+export class McpPanelService extends TypertRemoteService {
+  static inject = ['loader', 'tools']
+
+  /** Latest upstream payload per server namespace. */
+  private readonly statuses = new Map<string, McpServerStatus>()
+  /** Cumulative reconnect attempts observed per server namespace. */
+  private readonly reconnects = new Map<string, number>()
+  /** Epoch ms of the latest upstream event receipt per server namespace. */
+  private readonly observedAt = new Map<string, number>()
+  /** Latest passive-probe reachability per server namespace. */
+  private readonly probeStates = new Map<string, { state: 'reachable' | 'unreachable'; checkedAt: number }>()
+  /** Passive-probe loop guard: one sweep at a time. */
+  private passiveRunning = false
+
+  /**
+   * @param ctx - context carrying the loader and tool registry.
+   * @param config - resolved runtime settings; defaults apply for direct construction.
+   */
+  constructor(ctx: Context, private readonly config: McpPanelServiceConfig = DEFAULT_SERVICE_CONFIG) {
+    super(ctx, 'mcpPanel')
+    if (config.passiveProbeEnabled) {
+      const timer = setInterval(() => { void this.runPassiveProbes() }, config.passiveProbeIntervalMs)
+      // An armed probe timer must never hold the process open on its own.
+      timer.unref?.()
+      ctx.effect(() => () => { clearInterval(timer) }, 'dsh-mcp-panel: passive probe loop')
+    }
+  }
+
+  /**
+   * Record one upstream `mcp/status` payload (event or query-seed). A
+   * `connecting` payload with a positive attempt counts one reconnect.
+   *
+   * @param payload - post-transition status facts.
+   */
+  observe(payload: McpServerStatus): void {
+    if (typeof payload.serverName !== 'string' || payload.serverName === '') return
+    this.statuses.set(payload.serverName, payload)
+    this.observedAt.set(payload.serverName, Date.now())
+    if (payload.phase === 'connecting' && payload.attempt > 0) {
+      this.reconnects.set(payload.serverName, (this.reconnects.get(payload.serverName) ?? 0) + 1)
+    }
+  }
+
+  /**
+   * Assemble the current snapshot. Read-only: touches no configuration file
+   * and mutates no registry. Exported on the wire by the `mcpPanel/status`
+   * invocation descriptor in `./wire.ts` (registered through the package's
+   * `./typert` manifest) — no method decorator, so the built bundle stays
+   * plain ESM.
+   *
+   * @returns the wire snapshot (validated by the strict Typert codec on both faces).
+   */
+  status(): McpPanelSnapshot {
+    const rows: McpLoaderRow[] = []
+    for (const entry of this.ctx.loader.entries()) {
+      if (entry.options.name !== MCP_CLIENT_MODULE) continue
+      rows.push({
+        // options.id is the user-written patch id (entry.id prefixes enclosing
+        // group ids such as `include:`), so patch suggestions match on reload.
+        entryId: entry.options.id,
+        disabled: entry.disabled,
+        fiberPhase: entry.fiber === undefined ? null : FIBER_PHASE[entry.fiber.state] ?? null,
+        config: entry.options.config,
+      })
+    }
+    const schemas = this.ctx.tools.schemas()
+    const configuredNames = rows.map(row => serverNameOf(row.config, `entry:${row.entryId}`))
+    const groups = groupMcpTools(schemas, configuredNames)
+    return aggregateSnapshot({
+      rows,
+      groups,
+      facts: {
+        statuses: this.statuses,
+        reconnects: this.reconnects,
+        observedAt: this.observedAt,
+        probeStates: this.probeStates,
+      },
+      probes: this.probeViews(),
+      patchFile: this.patchFile(),
+      refreshIntervalMs: this.config.refreshIntervalMs,
+    })
+  }
+
+  /**
+   * Start a one-shot connectivity probe of one configured streamable-http
+   * server as an UNOWNED background job — panel-only, like the `mcp_probe`
+   * tool, but callable from the settings tab. Exported on the wire by the
+   * `mcpPanel/probe` invocation descriptor.
+   *
+   * @param serverName - configured namespace.
+   * @returns the started job id and where the result lands.
+   */
+  probe(serverName: string): ProbeStarted {
+    const target = this.rawEndpoint(serverName)
+    if (target === undefined) {
+      throw new Error(`dsh-mcp-panel: "${serverName}" is not a configured streamable-http MCP server`)
+    }
+    const jobs = this.ctx.get('jobs')
+    if (jobs === undefined) {
+      throw new Error('dsh-mcp-panel: ctx.jobs is not composed — the panel probe action needs a background-job registry')
+    }
+    const jobId = jobs.start({
+      kind: PROBE_KIND,
+      label: `mcp_probe ${serverName}`,
+      // Unowned: no model completion notice, readable by the panel only.
+      run: () => probeJob(target.url, target.headers, this.config.probeTimeoutMs),
+    })
+    return {
+      jobId,
+      note: 'Probe results are panel-only: Settings → Plugins → MCP.',
+    }
+  }
+
+  /** One passive-probe sweep over every configured streamable-http server. */
+  private async runPassiveProbes(): Promise<void> {
+    if (this.passiveRunning) return
+    this.passiveRunning = true
+    try {
+      for (const entry of this.ctx.loader.entries()) {
+        if (entry.options.name !== MCP_CLIENT_MODULE) continue
+        const serverName = serverNameOf(entry.options.config, `entry:${entry.options.id}`)
+        const target = this.rawEndpoint(serverName)
+        if (target === undefined) continue
+        const outcome = await probeEndpoint(target.url, target.headers, this.config.probeTimeoutMs, AbortSignal.timeout(this.config.probeTimeoutMs))
+        this.probeStates.set(serverName, { state: outcome.status === 'completed' ? 'reachable' : 'unreachable', checkedAt: Date.now() })
+      }
+    } finally {
+      this.passiveRunning = false
+    }
+  }
+
+  /**
+   * Resolve one server's raw endpoint for the probe tool. Credentials stay
+   * inside this return value and are used for the request only — they never
+   * reach a snapshot, a log, or a display.
+   *
+   * @param serverName - configured namespace.
+   * @returns the raw URL + configured headers, or `undefined` when the server
+   *   is not a configured streamable-http row.
+   */
+  rawEndpoint(serverName: string): { url: string; headers: Record<string, string> } | undefined {
+    for (const entry of this.ctx.loader.entries()) {
+      if (entry.options.name !== MCP_CLIENT_MODULE) continue
+      const config = entry.options.config
+      if (serverNameOf(config, `entry:${entry.id}`) !== serverName) continue
+      if (typeof config !== 'object' || config === null || Array.isArray(config)) return undefined
+      const row = config as Record<string, unknown>
+      if (row['transport'] !== 'streamable-http') return undefined
+      const url = row['url']
+      if (typeof url !== 'string' || url === '') return undefined
+      const headersValue = row['headers']
+      const headers: Record<string, string> = {}
+      if (typeof headersValue === 'object' && headersValue !== null && !Array.isArray(headersValue)) {
+        for (const [name, value] of Object.entries(headersValue as Record<string, unknown>)) {
+          if (typeof value === 'string') headers[name] = value
+        }
+      }
+      return { url, headers }
+    }
+    return undefined
+  }
+
+  /** Unowned `mcp-probe` background jobs, newest first, sanitized for display. */
+  private probeViews(): McpProbeView[] {
+    const jobs = this.ctx.get('jobs')
+    if (jobs === undefined) return []
+    return jobs
+      .list()
+      .filter(job => job.kind === PROBE_KIND)
+      .map(job => ({
+        id: job.id,
+        serverName: job.label.startsWith(PROBE_LABEL_PREFIX) ? job.label.slice(PROBE_LABEL_PREFIX.length) : job.label,
+        status: job.status,
+        startedAt: job.startedAt,
+        finishedAt: job.finishedAt ?? null,
+        detail: job.detail === undefined ? null : sanitizeText(job.detail),
+      }))
+      .reverse()
+      .slice(0, this.config.maxProbes)
+  }
+
+  /** Absolute path of the profile patch layer the suggestions name, or null. */
+  private patchFile(): string | null {
+    const base = this.ctx.baseUrl
+    if (typeof base !== 'string' || base === '') return null
+    const dir = base.startsWith('file://') ? fileURLToPath(base) : base
+    return join(dir, PROFILE_PATCH_FILENAME)
+  }
+}
+
+export default McpPanelService