The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/** Native hook installation is eager. Optional transcript and screen readers own no hook files. */
import { dirname, join } from 'node:path'
import { hookPreparationRoutes, runHookPreparation, type HookPreparationProof } from './kit/nativeHookFiles.js'
import { nativeHookLocations, type NativeHookOptions } from './kit/nativeLocations.js'
import { env } from '../config/env.js'
import { hookTokenPath } from '../lib/hookAuth.js'
import { VERSION } from '../version.js'
import { OPENCODE_LEGACY_PLUGIN, OPENCODE_TUI_PLUGIN, OPENCODE_LEGACY_REMOVAL, OPENCODE_VERSION } from './opencode/contract.js'
import { KILO_PLUGIN } from './kilo/contract.js'
import { PI_EXTENSION } from './pi/contract.js'
import { AMP_PLUGIN } from './amp/contract.js'
import { HERMES_HOOK_SETTINGS } from './hermes/contract.js'
import { opencodeMajorVersion, type OpencodeLaunchSnapshot } from './launchControl.js'
import { installNativePlugin, prepareNativePlugin, prepareNativePluginRemoval } from './kit/nativePlugin.js'
import { installNativeYamlHooks } from './kit/nativeHookYaml.js'
import { command } from './kit/notifyHooks.js'
import { hostPlatform } from './kit/windowsFiles.js'
import { GROK_HOOK_SETTINGS } from './grok/contract.js'
import { AGY_HOOK_SETTINGS } from './agy/contract.js'
import { COPILOT_HOOK_SETTINGS } from './copilot/contract.js'
import { CURSOR_HOOK_SETTINGS } from './cursor/contract.js'
import { COMMANDCODE_HOOK_SETTINGS } from './commandcode/contract.js'
import { DEVIN_HOOK_SETTINGS } from './devin/contract.js'
import { installNativeHookSettings } from './kit/nativeHookSettings.js'
import { unixSocketPath } from '../lib/localSocket.js'
export const installGrokHooks = (port: number, options?: NativeHookOptions): Promise<boolean> => installNativeHookSettings(options?.environment ? { ...GROK_HOOK_SETTINGS, file: join(nativeHookLocations(options.environment).GROK_HOME, 'hooks', 'harness.json') } : GROK_HOOK_SETTINGS, port, options)
export const installAgyHooks = (port: number, options?: NativeHookOptions): Promise<boolean> => installNativeHookSettings(options?.environment ? { ...AGY_HOOK_SETTINGS, file: join(nativeHookLocations(options.environment).AGY_CONFIG_DIR, 'hooks.json') } : AGY_HOOK_SETTINGS, port, options)
export const installCopilotHooks = (port: number, options?: NativeHookOptions): Promise<boolean> => installNativeHookSettings(options?.environment ? { ...COPILOT_HOOK_SETTINGS, file: join(nativeHookLocations(options.environment).COPILOT_HOME, 'hooks', 'harness.json') } : COPILOT_HOOK_SETTINGS, port, options)
export const installCursorHooks = (port: number, options?: NativeHookOptions): Promise<boolean> => installNativeHookSettings(options?.environment ? { ...CURSOR_HOOK_SETTINGS, file: join(nativeHookLocations(options.environment).CURSOR_CONFIG_DIR, 'hooks.json') } : CURSOR_HOOK_SETTINGS, port, options)
export const installCommandCodeHooks = (port: number, options?: NativeHookOptions): Promise<boolean> => installNativeHookSettings(options?.environment ? { ...COMMANDCODE_HOOK_SETTINGS, file: join(nativeHookLocations(options.environment).COMMANDCODE_HOME, 'settings.json') } : COMMANDCODE_HOOK_SETTINGS, port, options)
export const installDevinHooks = (port: number, options?: NativeHookOptions): Promise<boolean> => installNativeHookSettings(options?.environment ? { ...DEVIN_HOOK_SETTINGS, file: nativeHookLocations(options.environment).DEVIN_CONFIG_PATH } : DEVIN_HOOK_SETTINGS, port, options)
const pluginValues = (port: number) => ({
port: String(port), credential: JSON.stringify(hookTokenPath(env.ADAPTER_DATA_DIR)), version: JSON.stringify(VERSION),
// Named for the configured port, as the daemon's socket is, whichever port it was given.
socket: JSON.stringify(unixSocketPath(env.ADAPTER_DATA_DIR, env.PORT)),
})
export const installKiloPlugin = (port: number, options?: NativeHookOptions): Promise<boolean> => installNativePlugin(options?.environment ? { ...KILO_PLUGIN, file: join(nativeHookLocations(options.environment).KILO_PLUGIN_DIR, 'launcher-register.js') } : KILO_PLUGIN, pluginValues(port), options)
export const installPiExtension = (port: number, options?: NativeHookOptions): Promise<boolean> => installNativePlugin(options?.environment ? { ...PI_EXTENSION, file: join(nativeHookLocations(options.environment).PI_AGENT_DIR, 'extensions', 'launcher-register.ts') } : PI_EXTENSION, pluginValues(port), options)
export const installAmpPlugin = (port: number, options?: NativeHookOptions): Promise<boolean> => installNativePlugin(options?.environment ? { ...AMP_PLUGIN, file: join(nativeHookLocations(options.environment).AMP_PLUGIN_DIR, 'launcher-register.ts') } : AMP_PLUGIN, pluginValues(port), options)
// Windows: Hermes splits the line itself and starts the program with no shell (agent/shell_hooks.py `_spawn`, Hermes 0.22.7). It
// keeps double quotes as one word and backslashes as they are, which is the line `cmd` takes (`shlex.split(posix=False)`).
export const installHermesHooks = (port: number, selectedHome?: string, options?: NativeHookOptions, platform: NodeJS.Platform = hostPlatform()): Promise<boolean> =>
installNativeYamlHooks(HERMES_HOOK_SETTINGS, home => command(port, 'hermes', env.CODEX_HOME, home, options?.environment, platform === 'win32' ? 'cmd' : 'bash'), selectedHome,
{ ...options, createMissing: !!selectedHome && !!options?.environment })
/** Install both discovery surfaces for v1; v2 must not load our incompatible v1 export. */
interface OpencodeInstallation { port: number; executable?: string; major?: number | null; settling?: boolean; done: Promise<boolean>; proofs: HookPreparationProof[] }
const opencodeInstallations = new Map<string, { current: OpencodeInstallation; users: number }>()
async function waitForInstallation(installation: OpencodeInstallation, deadline: number): Promise<boolean | null> {
const remaining = deadline - performance.now()
if (remaining <= 0) return null
let timer: ReturnType<typeof setTimeout> | undefined
try {
return await Promise.race([installation.done, new Promise<null>(done => {
timer = setTimeout(() => done(null), remaining)
})])
} finally { clearTimeout(timer) }
}
export async function installOpencodePlugin(port: number, snapshot?: OpencodeLaunchSnapshot, options: NativeHookOptions = {}): Promise<boolean> {
const deadline = performance.now() + (options.timeoutMs ?? OPENCODE_VERSION.timeoutMs)
const root = options.environment ? nativeHookLocations(options.environment).OPENCODE_PLUGIN_DIR : dirname(OPENCODE_LEGACY_PLUGIN.file)
const legacyRule = { ...OPENCODE_LEGACY_PLUGIN, file: join(root, 'launcher-register.js') }
const tuiRule = { ...OPENCODE_TUI_PLUGIN, file: join(dirname(root), 'plugins', 'launcher-register', 'tui.js') }
const removalRule = { ...OPENCODE_LEGACY_REMOVAL, file: legacyRule.file }
let routes: ReturnType<typeof hookPreparationRoutes>
try { routes = hookPreparationRoutes([legacyRule.file, tuiRule.file]) } catch { return false }
const installation: OpencodeInstallation = { port, executable: snapshot?.identity, done: Promise.resolve(false), proofs: [] }
// Parent aliases can give startup and a captured launch different spellings
// for the same pair. Each caller still retains its own original route proof.
const reservation = JSON.stringify(routes.keys)
if (opencodeInstallations.size >= 128 && !opencodeInstallations.has(reservation)) return false
const previous = opencodeInstallations.get(reservation)?.current
const group = opencodeInstallations.get(reservation) ?? { current: installation, users: 0 }
// Include callers waiting before the lower-level disk reservation. Overflow
// cannot supersede an admitted owner or grow an unbounded promise chain.
if (group.users >= 16) return false
group.current = installation; group.users++
opencodeInstallations.set(reservation, group)
try {
installation.done = (async () => {
const values = pluginValues(port)
const major = snapshot ? snapshot.major : await opencodeMajorVersion()
installation.major = major
// A newer request may have installed an upgraded/downgraded engine's hooks
// while this probe waited. Only the latest request can change those files.
if (installation !== group.current || snapshot?.current() === false) return false
// Readiness can precede the maintenance write. A launch has a captured
// executable; maintenance does not, so their publications cannot be joined.
// Revoke the older owner through group.current, let its disk work settle,
// then inspect and prove this launch's own outputs within the same deadline.
if (previous && (previous.settling || previous.major !== undefined
&& (previous.port !== port || previous.executable !== installation.executable || previous.major !== major))) {
installation.settling = true
const settled = await waitForInstallation(previous, deadline)
installation.settling = false
if (settled === null || installation !== group.current || snapshot?.current() === false || options.current?.() === false) return false
}
// Keep the existing first-install route until installer-only continuation
// can return through launch preparation. A missing executable also gives
// null here; refusing it would prevent create from reaching its installer.
// Whole-launch preparation must confirm a version before native dispatch.
try { routes.verify(); return await runHookPreparation([legacyRule.file, tuiRule.file], async attempt => {
// Inspect both destinations before publishing. A foreign legacy plugin
// cannot authorize even the first half of an upgrade's writes.
const legacy = major === 1 ? prepareNativePlugin(legacyRule, values) : prepareNativePluginRemoval(removalRule)
const tui = prepareNativePlugin(tuiRule, values)
legacy.verify(); tui.verify()
const removedOrInstalled = await legacy.commit(attempt), installed = await tui.commit(attempt)
removedOrInstalled.verify(); installed.verify()
return snapshot?.current() !== false
}, { ...options, timeoutMs: Math.max(0, deadline - performance.now()), confirmed: proof => installation.proofs.push(proof), identity: JSON.stringify([port, snapshot?.identity, major]),
current: () => group.current.port === port && group.current.executable === installation.executable
&& group.current.major === major && performance.now() < deadline && snapshot?.current() !== false && options.current?.() !== false }) } catch (error) {
console.error('[hooks] OpenCode preparation held:', error)
return false
}
})()
let current = installation, installed = await current.done
while (current !== group.current) {
current = group.current
// Two healthy creates must not fail merely because they overlap. Follow the
// current installation without restoring an obsolete request's write rights.
// A port change or continuing churn cannot make this caller wait forever.
const remaining = deadline - performance.now()
if (current.port !== port || current.executable !== installation.executable || snapshot?.current() === false || options.current?.() === false || remaining <= 0) return false
const result = await waitForInstallation(current, deadline)
if (result === null) return false
installed = result
}
if (!installed || performance.now() >= deadline || options.current?.() === false || snapshot?.current() === false || current.proofs.some(proof => !proof.current())) return false
if (performance.now() >= deadline) return false
try { routes.verify() } catch { return false }
if (performance.now() >= deadline || options.current?.() === false || snapshot?.current() === false) return false
for (const proof of current.proofs) options.confirmed?.({ ...proof, current: () => {
try { routes.verify(); return proof.current() } catch { return false }
} })
return true
} finally { if (--group.users === 0) opencodeInstallations.delete(reservation) }
}