The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
/**
* Probe and install desktop runtime plugins from Git repositories.
* Pure helpers are exported for unit tests; IPC handlers in main.ts call the
* async entry points with a resolved git binary.
*/
import { spawn } from 'node:child_process'
import fs from 'node:fs'
import fsp from 'node:fs/promises'
import os from 'node:os'
import path from 'node:path'
import { parse as parseYaml } from 'yaml'
import {
desktopHalfSource,
PACKAGE_MARKER,
publishDesktopTree,
rootLayoutFilter,
withDesktopPluginsRoot,
writeDesktopHalfMarker
} from './desktop-plugins-root'
import { execGit, hiddenGitSpawnSpec } from './no-console-git'
import { stripLikePython, WIN_RESERVED_RE } from './plugin-files-guards'
const GITHUB_BROWSER_SEGMENTS = new Set(['tree', 'blob', 'commit'])
export interface ResolvedGitUrl {
gitUrl: string
subdir: string | null
}
export interface PluginComponentDetection {
agent: boolean
desktop: boolean
agentName: string | null
desktopName: string | null
desktopSourceSubdir: string | null
}
export interface PluginProbeResult {
ok: boolean
agent: boolean
desktop: boolean
agentName?: string | null
desktopName?: string | null
warnings: string[]
insecure: boolean
/** The commit that was read; an install of this source is held to it. */
sha?: string
error?: string
}
export interface DesktopPluginInstallResult {
ok: boolean
pluginName?: string
path?: string
error?: string
/** Refused: the reviewed commit is no longer in the source. The dialog reads the source again. */
sourceMoved?: boolean
}
/** `checkoutReviewedCommit`'s refusal, told apart by class rather than by its message. */
class ReviewedCommitUnavailable extends Error {}
export function resolvePluginGitUrl(identifier: string): ResolvedGitUrl {
const trimmed = identifier.trim()
if (!trimmed) {
throw new Error('Plugin identifier is required.')
}
if (/^(https?:\/\/|git@|ssh:\/\/|file:\/\/)/.test(trimmed)) {
if (trimmed.startsWith('https://github.com/')) {
const rest = trimmed.slice('https://github.com/'.length).split(/[?#]/)[0].replace(/\/+$/, '')
const parts = rest.split('/').filter(Boolean)
if (parts.length >= 3 && parts[2] && GITHUB_BROWSER_SEGMENTS.has(parts[2])) {
const repo = parts[1].replace(/\.git$/, '')
let subdir: string | null = null
if (parts[2] === 'tree' && parts.length >= 5) {
subdir = parts.slice(4).join('/').replace(/\/+$/, '') || null
}
return { gitUrl: `https://github.com/${parts[0]}/${repo}.git`, subdir }
}
}
if (trimmed.includes('#')) {
const hashIdx = trimmed.indexOf('#')
const gitUrl = trimmed.slice(0, hashIdx)
const subdir = trimmed.slice(hashIdx + 1).replace(/^\/+|\/+$/g, '') || null
return { gitUrl, subdir }
}
const marker = '.git/'
if (trimmed.includes(marker)) {
const idx = trimmed.indexOf(marker)
const gitUrl = trimmed.slice(0, idx + marker.length - 1)
const subdir = trimmed.slice(idx + marker.length).replace(/^\/+|\/+$/g, '') || null
return { gitUrl, subdir }
}
return { gitUrl: trimmed, subdir: null }
}
const parts = trimmed.split('/').filter(Boolean)
if (parts.length >= 2) {
const [owner, repo, ...rest] = parts
const gitUrl = `https://github.com/${owner}/${repo}.git`
const subdir = rest.join('/').replace(/\/+$/, '') || null
return { gitUrl, subdir }
}
throw new Error("Invalid plugin identifier. Use a Git URL or 'owner/repo' (optionally with a subdirectory).")
}
export function repoNameFromUrl(url: string): string {
let name = url.replace(/\/+$/, '')
if (name.endsWith('.git')) {
name = name.slice(0, -4)
}
name = name.split('/').pop() || name
if (name.includes(':')) {
name = name.split(':').pop() || name
name = name.split('/').pop() || name
}
return name
}
/** *name* when it can be one folder directly under the desktop-plugins root, else throw. It comes from
* the repository (a manifest's `name`, a subdirectory's last segment), so it must never reach a path
* unchecked: `..` would make a forced install replace the Hermes home. No separators, no leading dot
* (the root's staging folders use it), and none of the names Windows reads as something else (a colon
* makes `C:..` drive-relative, a device name opens the device, a trailing dot is dropped). The agent
* side's `_checked_name` refuses the same names (#146394). */
export function checkedDesktopFolderName(name: string): string {
const candidate = stripLikePython(name)
if (
!candidate ||
candidate.startsWith('.') ||
candidate.endsWith('.') ||
/[/\\:]/.test(candidate) ||
[...candidate].some(char => char.charCodeAt(0) < 32) ||
[...candidate].length > 128 ||
WIN_RESERVED_RE.test(candidate.split('.', 1)[0].replace(/ +$/, ''))
) {
throw new Error(`'${name}' is not a desktop plugin folder name: it must be a plain folder name, not a path.`)
}
return candidate
}
/** Stable on-disk folder for a desktop plugin. Never the clone temp dir or a generic `desktop/` folder. */
export function desktopPluginFolderName(gitUrl: string, subdir: string | null): string {
if (subdir) {
const last = subdir
.split(/[/\\]/)
.filter(part => part && part !== '.' && part !== 'desktop')
.pop()
if (last) {
return last
}
}
return repoNameFromUrl(gitUrl)
}
export function resolveSubdirWithin(cloneRoot: string, subdir: string): string {
const root = path.resolve(cloneRoot)
const candidate = path.resolve(root, subdir)
if (candidate !== root && !candidate.startsWith(root + path.sep)) {
throw new Error(`Plugin subdirectory '${subdir}' escapes the repository.`)
}
return candidate
}
function pathExistsSync(filePath: string): boolean {
try {
fs.accessSync(filePath)
return true
} catch {
return false
}
}
async function pathIsDirectory(filePath: string): Promise<boolean> {
try {
const stat = await fsp.stat(filePath)
return stat.isDirectory()
} catch {
return false
}
}
async function pathIsFile(filePath: string): Promise<boolean> {
try {
const stat = await fsp.stat(filePath)
return stat.isFile()
} catch {
return false
}
}
/** The desktop entry by the one rule the reconcile applies to an installed package too
* (`desktopHalfSource`): a root `plugin.js` wins over `desktop/plugin.js`. */
export function findDesktopEntry(pluginRoot: string): { entryFile: string; sourceSubdir: string } | null {
const sourceDir = desktopHalfSource(pluginRoot)
if (!sourceDir) {
return null
}
return { entryFile: path.join(sourceDir, 'plugin.js'), sourceSubdir: path.relative(pluginRoot, sourceDir) || '.' }
}
/** Files beside a `plugin.yaml` that the agent side loads: a `register(ctx)` package, or a dashboard
* tab/backend (`dashboard/manifest.json`, often with a `plugin_api.py`) the gateway mounts. */
const AGENT_PAYLOAD_FILES = ['__init__.py', path.join('dashboard', 'manifest.json')]
/** Whether a `plugin.yaml` folder has something for the agent side to load. A manifest alone is not
* enough: desktop-only plugins ship one beside `desktop/plugin.js` for metadata. Same rule as the
* gateway's `_yaml_ships_agent_payload` (hermes_cli/plugins_cmd_inspect.py); the shared cases live in
* tests/fixtures/plugin_component_detection.json. */
async function yamlShipsAgentPayload(pluginRoot: string, yamlPath: string): Promise<boolean> {
if (AGENT_PAYLOAD_FILES.some(rel => pathExistsSync(path.join(pluginRoot, rel)))) {
return true
}
// The loader's manifest-only language pack: declared locales plus the folder that holds them.
if (!(await pathIsDirectory(path.join(pluginRoot, 'locales')))) {
return false
}
try {
const manifest: unknown = parseYaml(await fsp.readFile(yamlPath, 'utf8'))
const locales = (manifest as { provides_locales?: unknown } | null)?.provides_locales
// Python truthiness, as the gateway judges it: an empty list or mapping declares nothing.
return locales !== null && typeof locales === 'object' ? Object.keys(locales).length > 0 : Boolean(locales)
} catch {
return false
}
}
export async function detectPluginComponents(pluginRoot: string): Promise<PluginComponentDetection> {
const yamlPath = ['plugin.yaml', 'plugin.yml']
.map(name => path.join(pluginRoot, name))
.find(candidate => pathExistsSync(candidate))
const hasYaml = yamlPath !== undefined
const hasPortable = pathExistsSync(path.join(pluginRoot, 'plugin.json'))
// `__init__.py` is one agent payload, not a requirement: a manifest-only package with a
// `dashboard/plugin_api.py` backend must install its agent half, or its desktop half lands alone and
// every `ctx.rest` call 404s.
const agent = (hasYaml && (await yamlShipsAgentPayload(pluginRoot, yamlPath))) || hasPortable
const desktopEntry = findDesktopEntry(pluginRoot)
const desktop = desktopEntry !== null
let agentName: string | null = null
if (agent) {
agentName = path.basename(pluginRoot)
if (hasYaml) {
try {
const text = await fsp.readFile(yamlPath, 'utf8')
const match = text.match(/^name:\s*['"]?([^'"\n]+)['"]?\s*$/m)
if (match?.[1]) {
agentName = match[1].trim()
}
} catch {
// Fall back to directory name.
}
} else if (hasPortable) {
try {
const raw = await fsp.readFile(path.join(pluginRoot, 'plugin.json'), 'utf8')
const parsed = JSON.parse(raw) as { name?: string }
if (parsed.name) {
agentName = parsed.name
}
} catch {
// Fall back to directory name.
}
}
}
const desktopName = desktop
? desktopEntry!.sourceSubdir === '.'
? path.basename(pluginRoot)
: path.basename(path.dirname(desktopEntry!.entryFile))
: null
return {
agent,
desktop,
agentName,
desktopName,
desktopSourceSubdir: desktopEntry?.sourceSubdir ?? null
}
}
function noninteractiveGitEnv(): NodeJS.ProcessEnv {
return {
...process.env,
GIT_TERMINAL_PROMPT: '0',
GIT_ASKPASS: 'echo',
SSH_ASKPASS: 'echo'
}
}
// Matches the backend's default `plugins.clone_timeout_seconds`.
const GIT_TIMEOUT_MS = 300_000
function runGit(gitBin: string, args: string[], cwd?: string): Promise<{ code: number; stderr: string }> {
return new Promise((resolve, reject) => {
const spec = hiddenGitSpawnSpec(gitBin, args, {
cwd,
env: noninteractiveGitEnv(),
stdio: ['ignore', 'ignore', 'pipe']
})
const child = spawn(spec.command, spec.args, spec.options)
let stderr = ''
const timer = setTimeout(() => {
child.kill('SIGKILL')
reject(new Error(`Git ${args[0]} timed out after ${GIT_TIMEOUT_MS / 1000} seconds.`))
}, GIT_TIMEOUT_MS)
child.stderr?.on('data', chunk => {
stderr += String(chunk)
})
child.on('error', err => {
clearTimeout(timer)
reject(err)
})
child.on('close', code => {
clearTimeout(timer)
resolve({ code: code ?? 1, stderr })
})
})
}
async function runGitOrThrow(gitBin: string, args: string[], cwd?: string): Promise<void> {
const { code, stderr } = await runGit(gitBin, args, cwd)
if (code !== 0) {
throw new Error(`Git ${args[0]} failed:\n${stderr.trim()}`)
}
}
/** Sparse-check-out only `subdir` via the classic pattern file, which older Git clients understand. */
function sparseCheckoutPattern(subdir: string): string {
return `/${subdir.replace(/^\/+|\/+$/g, '').replace(/([\\*?[])/g, '\\$1')}/\n`
}
// A subdirectory install is a blobless clone with a sparse checkout of that folder: a plugin inside
// a monorepo (Hindsight: 170 MB at depth 1, 2 MB for its plugin folder) otherwise downloads every
// file in the repository and times out on slow connections.
async function cloneToTemp(gitBin: string, gitUrl: string, subdir: string | null): Promise<string> {
const tmpRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'hermes-plugin-'))
try {
if (!subdir) {
await runGitOrThrow(gitBin, ['clone', '--depth', '1', gitUrl, tmpRoot])
return tmpRoot
}
await runGitOrThrow(gitBin, ['clone', '--depth', '1', '--filter=blob:none', '--no-checkout', gitUrl, tmpRoot])
await runGitOrThrow(gitBin, ['config', 'core.sparseCheckout', 'true'], tmpRoot)
await fsp.mkdir(path.join(tmpRoot, '.git', 'info'), { recursive: true })
await fsp.writeFile(path.join(tmpRoot, '.git', 'info', 'sparse-checkout'), sparseCheckoutPattern(subdir), 'utf8')
await runGitOrThrow(gitBin, ['checkout', 'HEAD'], tmpRoot)
return tmpRoot
} catch (err) {
await fsp.rm(tmpRoot, { recursive: true, force: true }).catch(() => undefined)
throw err
}
}
const COMMIT_SHA = /^[0-9a-f]{40}$/
async function headSha(gitBin: string, cloneRoot: string, revision = 'HEAD'): Promise<string> {
const { code, stdout, stderr } = await execGit(gitBin, ['rev-parse', revision], {
cwd: cloneRoot,
env: noninteractiveGitEnv(),
timeoutMs: GIT_TIMEOUT_MS
})
if (code !== 0) {
throw new Error(`Git rev-parse failed:\n${stderr.trim()}`)
}
return stdout.trim().toLowerCase()
}
/** Detach the clone at `sha`, the commit the install dialog showed: a branch that moved after review must
* not put down a tree nobody inspected. A source that no longer has it is refused. */
async function checkoutReviewedCommit(gitBin: string, cloneRoot: string, sha: string): Promise<void> {
const reviewed = sha.trim().toLowerCase()
if (!COMMIT_SHA.test(reviewed)) {
throw new Error('Installing a desktop plugin needs the full commit the install dialog reviewed.')
}
try {
if ((await headSha(gitBin, cloneRoot)) !== reviewed) {
await runGitOrThrow(gitBin, ['fetch', '--depth', '1', 'origin', reviewed], cloneRoot)
await runGitOrThrow(gitBin, ['checkout', '--detach', reviewed], cloneRoot)
}
// A catalog pin may name an annotated tag: HEAD is the commit it peels to.
if ((await headSha(gitBin, cloneRoot)) !== (await headSha(gitBin, cloneRoot, `${reviewed}^{commit}`))) {
throw new Error(`HEAD is not ${reviewed}.`)
}
} catch (err) {
throw new ReviewedCommitUnavailable(
`The commit you reviewed (${reviewed.slice(0, 12)}) could not be checked out; the source may have changed ` +
`since you reviewed it. Re-open the install dialog to review it again. ${err instanceof Error ? err.message : String(err)}`
)
}
}
async function resolvePluginRoot(cloneRoot: string, subdir: string | null): Promise<string> {
if (!subdir) {
return cloneRoot
}
const resolved = resolveSubdirWithin(cloneRoot, subdir)
if (!(await pathIsDirectory(resolved))) {
throw new Error(`Plugin subdirectory '${subdir}' does not exist in the repository.`)
}
return resolved
}
function insecureSchemeWarnings(gitUrl: string): { warnings: string[]; insecure: boolean } {
if (gitUrl.startsWith('http://') || gitUrl.startsWith('file://')) {
return {
warnings: ['This URL uses an insecure or local scheme. Prefer https:// or git@ for production installs.'],
insecure: true
}
}
return { warnings: [], insecure: false }
}
export async function probePluginRepo(gitBin: string, identifier: string): Promise<PluginProbeResult> {
try {
const { gitUrl, subdir } = resolvePluginGitUrl(identifier)
const { warnings, insecure } = insecureSchemeWarnings(gitUrl)
const cloneRoot = await cloneToTemp(gitBin, gitUrl, subdir)
try {
const pluginRoot = await resolvePluginRoot(cloneRoot, subdir)
const detected = await detectPluginComponents(pluginRoot)
const repoFallback = repoNameFromUrl(gitUrl)
if (!detected.agent && !detected.desktop) {
return {
ok: false,
agent: false,
desktop: false,
warnings,
insecure,
error: 'No agent or desktop plugin artifacts found in this repository.'
}
}
return {
ok: true,
agent: detected.agent,
desktop: detected.desktop,
agentName: detected.agentName ?? (detected.agent ? repoFallback : null),
desktopName: detected.desktop ? desktopPluginFolderName(gitUrl, subdir) : null,
warnings,
insecure,
sha: await headSha(gitBin, cloneRoot)
}
} finally {
await fsp.rm(cloneRoot, { recursive: true, force: true }).catch(() => undefined)
}
} catch (err) {
return {
ok: false,
agent: false,
desktop: false,
warnings: [],
insecure: false,
error: err instanceof Error ? err.message : String(err)
}
}
}
export async function installDesktopPluginFromGit(
gitBin: string,
identifier: string,
desktopPluginsRoot: string,
force = false,
/** The commit the install dialog reviewed (`probePluginRepo`'s `sha`): the half is installed from
* exactly that tree or refused. */
sha?: string
): Promise<DesktopPluginInstallResult> {
try {
const { gitUrl, subdir } = resolvePluginGitUrl(identifier)
const cloneRoot = await cloneToTemp(gitBin, gitUrl, subdir)
try {
if (sha !== undefined) {
await checkoutReviewedCommit(gitBin, cloneRoot, sha)
}
const pluginRoot = await resolvePluginRoot(cloneRoot, subdir)
const detected = await detectPluginComponents(pluginRoot)
if (!detected.desktop || !detected.desktopSourceSubdir) {
return { ok: false, error: 'No desktop plugin.js found in this repository.' }
}
const sourceDir =
detected.desktopSourceSubdir === '.' ? pluginRoot : path.join(pluginRoot, detected.desktopSourceSubdir)
// A repo carrying BOTH halves is one package: land its desktop half under
// the AGENT package name, so the copy this app makes and the one
// `reconcileUnifiedDesktopHalves` would make are the same folder (#100412)
// and the Plugins page pairs them into one row. A desktop-only repo keeps
// the git-derived folder name and stays a standalone plugin.
const packageName = detected.agent ? (detected.agentName ?? desktopPluginFolderName(gitUrl, subdir)) : null
const pluginName = checkedDesktopFolderName(packageName ?? desktopPluginFolderName(gitUrl, subdir))
const targetDir = path.join(desktopPluginsRoot, pluginName)
const targetPlugin = path.join(targetDir, 'plugin.js')
// Under the root's writer lock: the exists check and the publish must not
// interleave with a reconcile pass copying the same package folder.
return await withDesktopPluginsRoot<DesktopPluginInstallResult>(desktopPluginsRoot, async () => {
// Force replaces the folder only once the new tree has passed its checks and been staged
// (publishDesktopTree): a refused reinstall keeps the working copy.
if (!force && ((await pathIsDirectory(targetDir)) || (await pathIsFile(targetPlugin)))) {
return {
ok: false,
error: `Desktop plugin '${pluginName}' already exists. Enable force reinstall to replace it.`
}
}
// Staged copy + rename: a failed copy must not leave an empty `targetDir`
// that turns every retry into "already exists. Enable force reinstall".
// The half of a unified package is stamped with the package marker as
// part of that publication — without it the Plugins page cannot tell this
// copy belongs to the agent row (it sits on "copying…" forever) and the
// half loads default-enabled instead of opt-in.
await publishDesktopTree(
{ dir: sourceDir, plainWithin: cloneRoot },
targetDir,
async staged => {
if (!packageName) {
// A desktop-only repo is a standalone plugin. A package marker it
// ships would name another package's agent half as its own (pairing
// it on the Plugins page and letting it render that package's tool
// media), so only this installer or the reconcile pass writes one.
await fsp.rm(path.join(staged, PACKAGE_MARKER), { force: true })
return
}
await writeDesktopHalfMarker(staged, {
package: pluginName,
repo: gitUrl,
// The published folder, not the temp clone. The clone is deleted
// below; a source that disappears is ghost-pruned on the next
// reconcile when no local `plugins/<name>/desktop` exists to
// re-copy from (remote backend, or Desktop UI only). A later pass
// that does find the agent package still replaces this copy,
// because this path is not that package's `desktop/` dir.
source: targetDir,
sourceMtimeMs: (await fsp.stat(path.join(staged, 'plugin.js'))).mtimeMs
})
},
detected.desktopSourceSubdir === '.' ? rootLayoutFilter : undefined
)
if (!(await pathIsFile(targetPlugin))) {
return { ok: false, error: `Install completed but ${targetPlugin} is missing.` }
}
return { ok: true, pluginName, path: targetDir }
})
} finally {
await fsp.rm(cloneRoot, { recursive: true, force: true }).catch(() => undefined)
}
} catch (err) {
return {
ok: false,
error: err instanceof Error ? err.message : String(err),
...(err instanceof ReviewedCommitUnavailable ? { sourceMoved: true } : {})
}
}
}
/** Resolve git binary via execFile which path on unix; caller passes Windows-resolved path. */
export function runGitVersion(gitBin: string): Promise<boolean> {
return execGit(gitBin, ['--version'], { timeoutMs: 5_000 }).then(
result => result.code === 0,
() => false
)
}