@dshforge/agent-plugins 0.0.0-stage → 0.1.1

package/lib/discovery.js

@@ -0,0 +1,191 @@
+import { readdir, readFile, realpath, stat } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+import {
+  INVALID_AGENT_PLUGIN, errorMessage, invalidAgentPlugin, isMissingPath,
+  parseSkillDocument, validateManifest, validateMcpDocument, validateMcpServer,
+} from './validation.js'
+import { resolveExistingInside } from './paths.js'
+
+/** Discover Agent Plugins below one explicit user-owned directory. */
+export async function discoverAgentPlugins({ pluginsDirectory }) {
+  const plugins = []
+  const diagnostics = []
+  let entries
+  try {
+    entries = await readdir(pluginsDirectory, { withFileTypes: true })
+  } catch (error) {
+    if (isMissingPath(error)) return { plugins, diagnostics }
+    throw error
+  }
+
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+    const candidate = join(pluginsDirectory, entry.name)
+    let root
+    try {
+      root = await realpath(candidate)
+      if (!(await stat(root)).isDirectory()) continue
+    } catch (error) {
+      if (isMissingPath(error)) continue
+      throw error
+    }
+
+    let manifest
+    try {
+      const document = await readJson(root, join(root, 'plugin.json'))
+      const validated = validateManifest(document, join(root, 'plugin.json'))
+      manifest = validated.manifest
+      diagnostics.push(...validated.diagnostics.map(issue => ({ ...issue, plugin: manifest.name })))
+    } catch (error) {
+      if (isMissingPath(error) || error.code === INVALID_AGENT_PLUGIN) {
+        const reason = errorMessage(error)
+        diagnostics.push({ component: 'manifest', path: join(root, 'plugin.json'), message: reason, plugin: entry.name })
+        plugins.push({
+          name: entry.name, directoryName: entry.name, root, manifest: null, status: 'invalid', invalidReason: reason,
+          skills: [], mcpServers: [],
+        })
+        continue
+      }
+      throw error
+    }
+
+    const [skills, mcp] = await Promise.all([
+      discoverSkills(root, manifest.name, diagnostics),
+      discoverMcp(root, manifest, diagnostics),
+    ])
+    plugins.push({
+      name: manifest.name,
+      directoryName: entry.name,
+      root,
+      manifest,
+      status: 'ready',
+      skills,
+      mcpServers: mcp.servers,
+      mcpPresent: mcp.present,
+      ...mcp.error === undefined ? {} : { mcpError: mcp.error },
+    })
+  }
+
+  const seenSkills = new Set()
+  for (const plugin of plugins) {
+    for (const skill of plugin.skills) {
+      if (seenSkills.has(skill.name)) {
+        diagnostics.push({
+          component: 'skills', path: skill.path, plugin: plugin.name,
+          message: `duplicate skill ${JSON.stringify(skill.name)}; the first package in sorted order wins`,
+        })
+      }
+      seenSkills.add(skill.name)
+    }
+  }
+  return { plugins, diagnostics }
+}
+
+async function discoverSkills(root, pluginName, diagnostics) {
+  const skillsRoot = join(root, 'skills')
+  let resolvedRoot
+  try {
+    resolvedRoot = await resolveExistingInside(root, skillsRoot)
+    if (!(await stat(resolvedRoot)).isDirectory()) {
+      throw invalidAgentPlugin('skills must be a directory when present', skillsRoot)
+    }
+  } catch (error) {
+    if (isMissingPath(error)) return []
+    if (error.code === INVALID_AGENT_PLUGIN) {
+      diagnostics.push({ component: 'skills', path: skillsRoot, message: errorMessage(error), plugin: pluginName })
+      return []
+    }
+    throw error
+  }
+
+  const entries = await readdir(resolvedRoot, { withFileTypes: true })
+  const skills = []
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+    const directory = join(resolvedRoot, entry.name)
+    try {
+      const resolvedDirectory = await resolveExistingInside(root, directory)
+      if (!(await stat(resolvedDirectory)).isDirectory()) continue
+      const path = await resolveExistingInside(root, join(resolvedDirectory, 'SKILL.md'))
+      if (!(await stat(path)).isFile()) continue
+      const document = parseSkillDocument(await readFile(path, 'utf8'), entry.name, path)
+      skills.push({
+        name: document.name,
+        description: document.description,
+        path,
+        directory: resolvedDirectory,
+        packageDirectory: entry.name,
+        ...document.license === undefined ? {} : { license: document.license },
+        ...document.compatibility === undefined ? {} : { compatibility: document.compatibility },
+        ...document.metadata === undefined ? {} : { metadata: document.metadata },
+        ...document.allowedTools === undefined ? {} : { allowedTools: document.allowedTools },
+      })
+    } catch (error) {
+      if (isMissingPath(error)) continue
+      if (error.code === INVALID_AGENT_PLUGIN) {
+        diagnostics.push({ component: 'skills', path: directory, message: errorMessage(error), plugin: pluginName })
+        continue
+      }
+      throw error
+    }
+  }
+  return skills
+}
+
+async function discoverMcp(root, manifest, diagnostics) {
+  const path = join(root, 'mcp.json')
+  let document
+  try {
+    document = await readJson(root, path)
+  } catch (error) {
+    if (isMissingPath(error)) return { servers: [], present: false }
+    if (error.code === INVALID_AGENT_PLUGIN) return { servers: [], present: true, error: errorMessage(error) }
+    throw error
+  }
+
+  try {
+    validateMcpDocument(document, manifest.$schema, path)
+  } catch (error) {
+    if (error.code === INVALID_AGENT_PLUGIN) return { servers: [], present: true, error: errorMessage(error) }
+    throw error
+  }
+
+  const servers = []
+  for (const [name, config] of Object.entries(document.mcpServers).sort(([a], [b]) => a.localeCompare(b))) {
+    try {
+      validateMcpServer(name, config, path)
+      servers.push({ name, ...config })
+    } catch (error) {
+      if (error.code === INVALID_AGENT_PLUGIN) {
+        diagnostics.push({ component: 'mcp', path, message: errorMessage(error), plugin: manifest.name })
+        continue
+      }
+      throw error
+    }
+  }
+  return { servers, present: true }
+}
+
+/** Revalidate and read one skill body for an on-demand provider get(). */
+export async function loadAgentSkill({ pluginRoot, skillDirectory, packageDirectory, signal }) {
+  const root = await realpath(pluginRoot)
+  validateManifest(await readJson(root, join(root, 'plugin.json')), join(root, 'plugin.json'))
+  const resolvedSkillsRoot = await resolveExistingInside(root, join(root, 'skills'))
+  const directory = await resolveExistingInside(root, skillDirectory)
+  if (dirname(directory) !== resolvedSkillsRoot || !(await stat(directory)).isDirectory()) return undefined
+  const path = await resolveExistingInside(root, join(directory, 'SKILL.md'))
+  if (!(await stat(path)).isFile()) return undefined
+  const expectedName = packageDirectory ?? basename(skillDirectory)
+  return parseSkillDocument(await readFile(path, { encoding: 'utf8', signal }), expectedName, path)
+}
+
+async function readJson(root, path) {
+  const resolved = await resolveExistingInside(root, path)
+  if (!(await stat(resolved)).isFile()) throw invalidAgentPlugin('expected a regular JSON file', path)
+  const text = await readFile(resolved, 'utf8')
+  try {
+    return JSON.parse(text)
+  } catch (error) {
+    throw invalidAgentPlugin(`invalid JSON: ${errorMessage(error)}`, path)
+  }
+}

package/lib/index.js

@@ -0,0 +1,45 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { discoverAgentPlugins } from './discovery.js'
+import { createAgentSkillProvider } from './skills.js'
+import { registerAgentPluginsRpc } from './rpc.js'
+import { mountAgentPluginMcpServers } from './mcp.js'
+import { installAgentPlugin } from './install.js'
+
+export const name = 'agent-plugins'
+export const inject = ['skills', 'connection', 'webServer']
+
+/** Mount Agent Plugin discovery and the strict Skills provider. */
+export async function apply(ctx) {
+  const pluginsDirectory = join(homedir(), '.agents', 'plugins')
+  let invalidateSkills = () => {}
+  ctx.effect(() => ctx.skills.registerProvider((control) => {
+    invalidateSkills = control.invalidate
+    return createAgentSkillProvider({ pluginsDirectory })
+  }), 'agent-plugins: skills provider')
+  const dataDirectory = join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'agent-plugins', 'data')
+  let catalog = await discoverAgentPlugins({ pluginsDirectory })
+  const install = async (spec, signal) => {
+    const installed = await installAgentPlugin({ pluginsDirectory, spec, signal })
+    catalog = await discoverAgentPlugins({ pluginsDirectory })
+    invalidateSkills()
+    ctx.emit('plugin-manager/changed', { reason: 'install' })
+    const plugin = catalog.plugins.find(entry => entry.directoryName === installed.name && entry.status === 'ready')
+    if (plugin !== undefined) await mountAgentPluginMcpServers(ctx, [plugin], { dataDirectory })
+    return installed
+  }
+  let rpcRegistered = false
+  for (const issue of catalog.diagnostics) {
+    ctx.logger.warn(`[agent-plugins] ${issue.plugin ?? 'catalog'}: ${issue.message}`)
+  }
+  const register = () => {
+    if (rpcRegistered || ctx.get('webServer') === undefined) return
+    rpcRegistered = true
+    ctx.effect(() => registerAgentPluginsRpc(ctx, () => catalog, { install }), 'agent-plugins: catalog route')
+  }
+  register()
+  ctx.on('internal/service', (name) => {
+    if (name === 'webServer') register()
+  })
+  await mountAgentPluginMcpServers(ctx, catalog.plugins, { dataDirectory })
+}

package/lib/install.js

@@ -0,0 +1,199 @@
+import { execa } from 'execa'
+import { cp, mkdir, mkdtemp, readFile, rename, rm, rmdir } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { resolveExistingInside } from './paths.js'
+import { errorMessage, invalidAgentPlugin, validateManifest } from './validation.js'
+
+const GIT_OPERATION_TIMEOUT_MS = 15_000
+const GIT_PROBE_TIMEOUT_MS = 5_000
+const HTTP_GIT_URL = /^(?:git\+)?https:\/\//i
+const SCP_GIT_URL = /^git@[^:\s]+:[^\s]+$/i
+const SSH_GIT_URL = /^(?:git\+)?ssh:\/\//i
+const FILE_GIT_URL = /^(?:git\+)?file:\/\//i
+const PATH_PARAMETER = /&path(?:=|:)([^#]*)$/
+const PATH_SEGMENT = /^[A-Za-z0-9._@+-]+$/
+const REF_PATTERN = /^[A-Za-z0-9._~^/:@+-]+$/
+
+/** Parse a DSH-compatible Git install spec with optional ref and path parameter. */
+export function parseGitInstallSpec(raw) {
+  const input = raw.trim()
+  if (input === '' || input.length > 2048 || input.startsWith('-')) {
+    throw installError('agent-plugins/invalid-spec', 'Git install spec must be a non-empty value of at most 2048 characters')
+  }
+  let base = input
+  let path
+  const pathMatch = PATH_PARAMETER.exec(base)
+  if (pathMatch) {
+    path = normalizePackagePath(pathMatch[1])
+    base = base.slice(0, pathMatch.index)
+  }
+  const hashAt = base.indexOf('#')
+  const ref = hashAt === -1 ? undefined : base.slice(hashAt + 1)
+  const address = hashAt === -1 ? base : base.slice(0, hashAt)
+  if (ref !== undefined && !REF_PATTERN.test(ref)) {
+    throw installError('agent-plugins/invalid-spec', 'Git ref contains unsupported characters')
+  }
+  if (HTTP_GIT_URL.test(address)) {
+    const url = new URL(address.replace(/^git\+/i, ''))
+    if (url.username !== '' || url.password !== '' || url.search !== '' || url.hostname === '') {
+      throw installError('agent-plugins/invalid-spec', 'HTTPS Git URL must not contain credentials or a query')
+    }
+    if (url.pathname.split('/').filter(Boolean).length < 2 || /\.(?:tgz|tar\.gz)$/i.test(url.pathname)) {
+      throw installError('agent-plugins/invalid-spec', 'HTTPS Git URL must name a repository, not a tarball')
+    }
+    return { kind: 'https', url: `${url.href}${url.href.endsWith('.git') ? '' : '.git'}`, path, ref }
+  }
+  if (SCP_GIT_URL.test(address)) return { kind: 'scp', url: address, path, ref }
+  if (SSH_GIT_URL.test(address)) {
+    const url = new URL(address.replace(/^git\+/i, ''))
+    if (url.hostname === '' || url.pathname === '' || url.password !== '' || url.search !== '') {
+      throw installError('agent-plugins/invalid-spec', 'SSH Git URL must name a host and repository without credentials or a query')
+    }
+    return { kind: 'ssh', url: address.replace(/^git\+/i, ''), path, ref }
+  }
+  if (FILE_GIT_URL.test(address)) {
+    const url = new URL(address.replace(/^git\+/i, ''))
+    if (url.hostname !== '' || url.pathname === '' || url.search !== '') {
+      throw installError('agent-plugins/invalid-spec', 'Local file Git URL must have no host or query')
+    }
+    return { kind: 'file', url: address.replace(/^git\+/i, ''), path, ref }
+  }
+  throw installError('agent-plugins/invalid-spec', 'Expected an HTTPS .git URL, an SCP-style git@host:path, or an SSH Git URL')
+}
+
+/** Install one Agent Plugin without requiring package.json or running install scripts. */
+export async function installAgentPlugin({ pluginsDirectory, spec, signal }) {
+  const parsed = parseGitInstallSpec(spec)
+  const temporary = await mkdtemp(join(tmpdir(), 'agent-plugin-install-'))
+  try {
+    const repository = join(temporary, 'repo')
+    const transport = await chooseGitTransport(parsed, temporary, signal)
+    await runGit(temporary, ['init', '--quiet', repository], signal)
+    await runGit(temporary, ['-C', repository, 'remote', 'add', 'origin', transport], signal)
+    if (parsed.path !== undefined) {
+      await runGit(temporary, ['-C', repository, 'sparse-checkout', 'set', parsed.path], signal)
+    }
+    await runGit(temporary, ['-C', repository, 'fetch', '--depth', '1', 'origin', parsed.ref ?? 'HEAD'], signal)
+    await runGit(temporary, ['-C', repository, 'checkout', '--detach', 'FETCH_HEAD'], signal)
+
+    const root = await resolveExistingInside(repository, join(repository, parsed.path ?? ''))
+    const manifestPath = join(root, 'plugin.json')
+    let document
+    try {
+      document = JSON.parse(await readFile(manifestPath, 'utf8'))
+    } catch (error) {
+      throw invalidAgentPlugin(`invalid plugin.json: ${errorMessage(error)}`, manifestPath)
+    }
+    const { manifest } = validateManifest(document, manifestPath)
+    await mkdir(pluginsDirectory, { recursive: true })
+    const destination = join(pluginsDirectory, manifest.name)
+    const staging = join(pluginsDirectory, `.${manifest.name}.install-${randomUUID()}`)
+    await cp(root, staging, {
+      recursive: true, force: false, errorOnExist: true, verbatimSymlinks: true,
+      filter: source => source !== join(root, '.git'),
+    })
+    try {
+      await mkdir(destination)
+      await rmdir(destination)
+      await rename(staging, destination)
+    } catch (error) {
+      await rm(staging, { recursive: true, force: true })
+      if (error.code === 'EEXIST' || error.code === 'ENOTEMPTY') {
+        throw installError('agent-plugins/already-installed', `Agent Plugin ${manifest.name} is already installed`)
+      }
+      throw error
+    }
+    return { name: manifest.name, root: destination, manifest }
+  } finally {
+    await rm(temporary, { recursive: true, force: true })
+  }
+}
+
+function normalizePackagePath(value) {
+  const path = value.replace(/^\/+/, '')
+  if (path === '' || path.includes('\\') || path.split('/').some(segment => segment === '' || segment === '.' || segment === '..' || !PATH_SEGMENT.test(segment))) {
+    throw installError('agent-plugins/invalid-spec', 'Git path must be a relative directory without . or .. segments')
+  }
+  return path
+}
+
+export async function chooseGitTransport(spec, cwd, signal, probe = readable) {
+  if (spec.kind === 'https') {
+    if (await probe(spec.url, cwd, signal)) return spec.url
+    const ssh = sshGitSpec(spec)
+    if (signal?.aborted) throw installError('agent-plugins/cancelled', 'Git installation was cancelled')
+    if (ssh !== undefined && await probe(ssh, cwd, signal)) return ssh
+    if (signal?.aborted) throw installError('agent-plugins/cancelled', 'Git installation was cancelled')
+    return spec.url
+  }
+  if (spec.kind === 'scp' || spec.kind === 'ssh') {
+    if (await probe(spec.url, cwd, signal)) return spec.url
+    const https = httpsGitSpec(spec)
+    if (signal?.aborted) throw installError('agent-plugins/cancelled', 'Git installation was cancelled')
+    if (https !== undefined && await probe(https, cwd, signal)) return https
+    if (signal?.aborted) throw installError('agent-plugins/cancelled', 'Git installation was cancelled')
+  }
+  return spec.url
+}
+
+function httpsGitSpec(spec) {
+  if (spec.kind === 'scp') {
+    const match = /^git@([^:]+):(.+)$/.exec(spec.url)
+    return match === null ? undefined : `https://${match[1]}/${match[2]}`
+  }
+  const url = new URL(spec.url)
+  if (url.hostname === '' || url.pathname === '') return undefined
+  return `https://${url.hostname}${url.pathname}`
+}
+
+function sshGitSpec(spec) {
+  const url = new URL(spec.url)
+  if (url.username !== '' || url.password !== '' || url.search !== '') return undefined
+  return `git@${url.hostname}:${url.pathname.replace(/^\//, '')}`
+}
+
+async function readable(repository, cwd, signal) {
+  try {
+    await runGit(cwd, ['-c', 'core.askPass=', 'ls-remote', '--exit-code', '--', repository, 'HEAD'], signal, GIT_PROBE_TIMEOUT_MS)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function runGit(cwd, args, signal, timeoutMs = GIT_OPERATION_TIMEOUT_MS) {
+  const result = await execa('git', args, {
+    cwd,
+    env: {
+      ...process.env,
+      LC_ALL: 'C',
+      GIT_TERMINAL_PROMPT: '0',
+      GCM_INTERACTIVE: 'never',
+      GIT_ASKPASS: '',
+      SSH_ASKPASS: '',
+      SSH_ASKPASS_REQUIRE: 'never',
+    },
+    extendEnv: false,
+    stdin: 'ignore',
+    stdout: 'pipe',
+    stderr: 'pipe',
+    reject: false,
+    timeout: timeoutMs,
+    cancelSignal: signal,
+    killDescendants: true,
+    killSignal: 'SIGKILL',
+  })
+  if (result.failed) {
+    const detail = (result.stderr || result.stdout || result.shortMessage || 'git command failed').trim().slice(-2000)
+    throw installError('agent-plugins/git-failed', detail)
+  }
+  return result
+}
+
+function installError(code, message) {
+  const error = new Error(message)
+  error.code = code
+  return error
+}

package/lib/mcp.js

@@ -0,0 +1,186 @@
+import { createHash, randomBytes } from 'node:crypto'
+import { createServer } from 'node:http'
+import { Readable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import { mkdir } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import * as McpClient from '@deepseek-ai/dsh-mcp-client'
+import { resolveLaunchInside } from './paths.js'
+import { errorMessage, invalidAgentPlugin } from './validation.js'
+
+/** Derive a stable DSH-safe server identity from package directory and server key. */
+export function mcpServerName(packageDirectory, serverKey) {
+  const identity = `${packageDirectory}/${serverKey}`
+  const suffix = createHash('sha256').update(identity).digest('hex').slice(0, 8)
+  const normalized = identity.replace(/[^A-Za-z0-9_-]/g, '_').replace(/^_+|_+$/g, '') || 'agent'
+  return `${normalized.slice(0, 32 - suffix.length - 1)}_${suffix}`
+}
+
+/** Expand both plugin variables once, without rescanning replacement text. */
+export function expandPluginVariables(value, pluginRoot, pluginData) {
+  return value.replace(/\$\{PLUGIN_(ROOT|DATA)\}/g, (_match, name) => name === 'ROOT' ? pluginRoot : pluginData)
+}
+
+/** Translate one validated Agent Plugins server into the existing DSH client config. */
+export async function createMcpClientConfig({ plugin, server, dataDirectory }) {
+  const serverName = mcpServerName(plugin.directoryName, server.name)
+  if (server.type === 'streamable-http') {
+    return McpClient.Config({
+      transport: 'streamable-http',
+      serverName,
+      url: server.url,
+      headers: server.headers ?? {},
+      failOnStartupError: false,
+    })
+  }
+  if (server.type !== 'stdio') {
+    throw invalidAgentPlugin(`unsupported MCP transport ${JSON.stringify(server.type)}`, join(plugin.root, 'mcp.json'))
+  }
+
+  const pluginRoot = plugin.root
+  const pluginData = join(dataDirectory, plugin.directoryName)
+  await mkdir(pluginData, { recursive: true })
+  const command = server.command.startsWith('./')
+    ? await resolveLaunchInside(pluginRoot, resolve(pluginRoot, server.command))
+    : server.command
+  const rawCwd = server.cwd ?? '${PLUGIN_ROOT}'
+  const expandedCwd = expandPluginVariables(rawCwd, pluginRoot, pluginData)
+  const cwdRoot = rawCwd.startsWith('${PLUGIN_DATA}') ? pluginData : pluginRoot
+  const cwd = await resolveLaunchInside(cwdRoot, resolve(cwdRoot, expandedCwd))
+  const args = (server.args ?? []).map(value => expandPluginVariables(value, pluginRoot, pluginData))
+  const env = Object.fromEntries(Object.entries(server.env ?? {})
+    .map(([name, value]) => [name, expandPluginVariables(value, pluginRoot, pluginData)]))
+  env.PLUGIN_ROOT = pluginRoot
+  env.PLUGIN_DATA = pluginData
+
+  return McpClient.Config({
+    transport: 'stdio',
+    serverName,
+    command,
+    args,
+    env,
+    cwd,
+    failOnStartupError: false,
+  })
+}
+
+/** Mount every valid server independently; one failure never blocks siblings. */
+export async function mountAgentPluginMcpServers(ctx, plugins, { dataDirectory }) {
+  const proxies = []
+  const lifecycle = { disposed: false }
+  ctx.effect(() => async () => {
+    lifecycle.disposed = true
+    await Promise.all(proxies.map(proxy => proxy.close()))
+  }, 'agent-plugins: redirect-denying HTTP forwarders')
+  const starts = []
+  for (const plugin of plugins) {
+    for (const server of plugin.mcpServers) {
+      starts.push((async () => {
+        let proxy
+        try {
+          const config = await createMcpClientConfig({ plugin, server, dataDirectory })
+          const guarded = await guardMcpEndpoint(server, config, proxies, lifecycle)
+          proxy = guarded.proxy
+          if (lifecycle.disposed) throw new Error('Agent Plugins mount was disposed during startup')
+          return await ctx.plugin(McpClient, guarded.config)
+        } catch (error) {
+          if (proxy) {
+            const index = proxies.indexOf(proxy)
+            if (index >= 0) proxies.splice(index, 1)
+            await proxy.close().catch(closeError => {
+              ctx.logger.warn(`[agent-plugins] MCP ${plugin.name}/${server.name}: redirect guard cleanup failed: ${errorMessage(closeError)}`)
+            })
+          }
+          ctx.logger.warn(`[agent-plugins] MCP ${plugin.name}/${server.name}: ${errorMessage(error)}`)
+          return undefined
+        }
+      })())
+    }
+  }
+  return (await Promise.all(starts)).filter(Boolean)
+}
+
+/** Refuse every redirect response for credentialed endpoints, per actual response. */
+async function guardMcpEndpoint(server, config, proxies, lifecycle) {
+  if (server.type !== 'streamable-http' || Object.keys(server.headers ?? {}).length === 0) return { config, proxy: undefined }
+  const proxy = await createRedirectGuard(server.url)
+  if (lifecycle.disposed) {
+    await proxy.close()
+    throw new Error('Agent Plugins mount was disposed during proxy creation')
+  }
+  proxies.push(proxy)
+  return { config: { ...config, url: proxy.url }, proxy }
+}
+
+async function createRedirectGuard(targetUrl) {
+  const token = randomBytes(16).toString('hex')
+  const controllers = new Set()
+  const server = createServer(async (request, response) => {
+    const requestUrl = new URL(request.url, 'http://127.0.0.1')
+    if (requestUrl.pathname !== `/${token}`) {
+      response.writeHead(404).end()
+      return
+    }
+    const upstreamUrl = new URL(targetUrl)
+    if (requestUrl.search) upstreamUrl.search = requestUrl.search
+    const controller = new AbortController()
+    controllers.add(controller)
+    response.on('close', () => controller.abort())
+    try {
+      const headers = { ...request.headers }
+      delete headers.host
+      delete headers.connection
+      delete headers['content-length']
+      delete headers['transfer-encoding']
+      const upstream = await fetch(upstreamUrl, {
+        method: request.method,
+        headers,
+        body: ['GET', 'HEAD'].includes(request.method) ? undefined : request,
+        duplex: 'half',
+        redirect: 'manual',
+        signal: controller.signal,
+      })
+      if ([301, 302, 303, 307, 308].includes(upstream.status)) {
+        response.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' })
+        response.end('Agent Plugins redirect with configured headers refused')
+        return
+      }
+      const responseHeaders = {}
+      for (const [name, value] of upstream.headers) {
+        if (!['connection', 'keep-alive', 'transfer-encoding', 'content-length', 'content-encoding'].includes(name)) {
+          responseHeaders[name] = value
+        }
+      }
+      response.writeHead(upstream.status, responseHeaders)
+      if (upstream.body) await pipeline(Readable.fromWeb(upstream.body), response, { signal: controller.signal })
+      else response.end()
+    } catch (error) {
+      if (!controller.signal.aborted) {
+        if (response.headersSent) {
+          response.destroy()
+        } else {
+          response.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' })
+          response.end('MCP upstream request failed')
+        }
+      }
+    } finally {
+      controllers.delete(controller)
+    }
+  })
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve))
+  const address = server.address()
+  if (!address || typeof address === 'string') throw new Error('unable to bind MCP redirect guard')
+  let closed = false
+  return {
+    url: `http://127.0.0.1:${address.port}/${token}`,
+    async close() {
+      if (closed) return
+      closed = true
+      for (const controller of controllers) controller.abort()
+      server.close()
+      server.closeAllConnections()
+      server.closeIdleConnections()
+      server.unref()
+    },
+  }
+}

package/lib/paths.js

@@ -0,0 +1,47 @@
+import { realpath } from 'node:fs/promises'
+import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+import { invalidAgentPlugin, isMissingPath } from './validation.js'
+
+/** Whether target resolves lexically inside root, including root itself. */
+export function pathInside(root, target) {
+  const child = relative(root, target)
+  return child === '' || (child !== '..' && !child.startsWith(`..${sep}`) && !isAbsolute(child))
+}
+
+/** Resolve an existing path and require it to remain inside the resolved root. */
+export async function resolveExistingInside(root, candidate) {
+  const resolvedRoot = await realpath(root)
+  const resolvedCandidate = await realpath(candidate)
+  if (!pathInside(resolvedRoot, resolvedCandidate)) {
+    throw invalidAgentPlugin('package path resolves outside the plugin root', candidate)
+  }
+  return resolvedCandidate
+}
+
+/** Resolve a launch path even when its final segments do not exist yet. */
+export async function resolveLaunchInside(root, candidate) {
+  const resolvedRoot = await realpath(root)
+  const resolvedCandidate = await canonicalizeWithMissing(candidate)
+  if (!pathInside(resolvedRoot, resolvedCandidate)) {
+    throw invalidAgentPlugin('launch path resolves outside its allowed root', candidate)
+  }
+  return resolvedCandidate
+}
+
+async function canonicalizeWithMissing(candidate) {
+  const absolute = resolve(candidate)
+  const suffix = []
+  let current = absolute
+  while (true) {
+    try {
+      const resolved = await realpath(current)
+      return suffix.length === 0 ? resolved : resolve(resolved, ...suffix)
+    } catch (error) {
+      if (!isMissingPath(error)) throw error
+      const parent = dirname(current)
+      if (parent === current) throw error
+      suffix.unshift(basename(current))
+      current = parent
+    }
+  }
+}