Skip to content

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.

17.1 KB
Raw Blame
/** The notify.mjs command and JSON merge primitives shared by shell-hook engines. */
import { existsSync } from 'node:fs'
import { basename, dirname, isAbsolute, join, posix, win32 } from 'node:path'
import { fileURLToPath } from 'node:url'
import { env } from '../../config/env.js'
import { engineName } from '../../lib/agentNames.js'
import { managedNodePath } from '../../lib/nodeRuntime.js'
import { insideWindowsRoots } from '../../lib/secureState.js'
import { STABLE_NOTIFY } from '../../lib/windows/installLayout.js'
import { HookPreparationHeld } from './nativeHookFiles.js'
import { cursorDataDir } from '../cursor/contract.js'
import { nativeHookLocations } from './nativeLocations.js'
import { hostPlatform } from './windowsFiles.js'

// notify.mjs location depends on the layout (import.meta.url is the REAL executing file at runtime):
//  - packaged/bundled: cli.js at ~/.harness/cli/cli.js → notify.mjs is a SIBLING (dist/ bundle too).
//  - a core started from the lean bundle (leanEntry.ts): its file is lean/<sha>/ in the data folder, which
//    holds no notify.mjs, and its script (process.argv[1]) is the cli.js it was read from: the sibling of that.
//  - dev/per-file:      notifyHooks.js at <appRoot>/{src,dist}/engines/kit/ → ../../../hook/notify.mjs.
// Prefer the sibling, fall back to the dev path.
const cliDir = dirname(fileURLToPath(import.meta.url))

/**
 * Where notify.mjs is, best first. Windows' installed layout (lib/windows/installLayout.ts) keeps one CLI folder per
 * version, with a stable `cli\notify.mjs` beside them that the updater refreshes. The hook lines name that one, so
 * they do not change at each update, and Codex does not ask to review them again.
 */
export function hookScriptCandidates(dir: string, script: string | undefined, platform: NodeJS.Platform = hostPlatform(),
  cliRoot: string = env.ADAPTER_CLI_DIR): string[] {
  const stable = platform === 'win32' && insideWindowsRoots(dir, [cliRoot]) ? [win32.join(cliRoot, STABLE_NOTIFY)] : []
  return [...stable, join(dir, 'notify.mjs'), ...(script ? [join(dirname(script), 'notify.mjs')] : []), join(dir, '..', '..', '..', 'hook', 'notify.mjs')]
}
export const HOOK_SCRIPT = hookScriptCandidates(cliDir, process.argv[1]).find(existsSync) ?? join(cliDir, '..', '..', '..', 'hook', 'notify.mjs')

/** An engine that declares no Windows hook runner gets no hooks there. That is said once per install and is not a failure. */
export function hooksNotOnWindows(engine: string): true {
  console.log(`[hooks] ${engine} hooks are not installed on Windows yet`)
  return true
}

/**
 * The log line for an install that did not happen, when [error] says why: on Windows one sentence, no stack. A refused
 * hook line (quoteHookCommand) or a held file is the person's to read, and a stack trace there buried the reason (B4.10
 * VM log). Null for any other error or platform: the caller logs as before, so mac and Linux logs do not change.
 */
export function hooksNotInstalled(engine: NotifyEngine, error: unknown, platform: NodeJS.Platform): string | null {
  if (platform !== 'win32' || !(error instanceof HookPreparationHeld)) return null
  return `[hooks] ${engineName(engine)} hooks are not installed: ${error.reason}`
}

/**
 * A hook rule as a preparation's identity names it (`runHookPreparation`'s `identity`: a refresh and a launch with
 * the same one share a preparation). Off Windows `win32Runner` is left out, so the identity is byte for byte what it
 * was before Windows hooks: mac and Linux do not change. The other keys keep their order.
 */
export function identitySettings<T extends object>(settings: T, platform: NodeJS.Platform = hostPlatform()): T | Omit<T, 'win32Runner'> {
  if (platform === 'win32') return settings
  const { win32Runner: _runner, ...rest } = settings as T & { win32Runner?: unknown }
  return rest
}

export interface CommandHook {
  type: string
  command: string
  /** Exec form: the program in `command`, these its arguments, no shell (Claude Code on Windows, B4.6). */
  args?: string[]
  timeout?: number
}
export interface HookBlock {
  matcher?: string
  hooks: CommandHook[]
}
export type Settings = { hooks?: Record<string, HookBlock[]> } & Record<string, unknown>

function shellQuote(value: string): string {
  return `'${value.replace(/'/g, `'\\''`)}'`
}

/**
 * What runs an engine's hook command. Each engine declares it for Windows (facets/hooks.ts `HookSettings.win32Runner`,
 * nativeHookSettings.ts `NativeHookSettings.win32Runner`). Off Windows every engine runs its hooks in a POSIX shell (`bash`).
 * - `argv`: the engine starts the program with its arguments and no shell (Claude Code's exec form, `command` + `args`).
 * - `bash`: a POSIX shell reads the line.
 * - `cmd`: `cmd.exe` reads it, meant for a line the engine wraps in quotes (`/d /s /c "…"` — Command Code via Node's
 *   shell:true). It refuses `" % ! & | < > ^ ( )` and a trailing backslash rather than escape them.
 * - `powershell`: PowerShell reads it (Copilot CLI's `command` fills its `powershell` field on Windows; Codex runs it with
 *   `powershell.exe -NoProfile -Command`, its Windows session shell).
 */
export type HookRunner = 'argv' | 'bash' | 'cmd' | 'powershell'

const BARE_WORD = /^[A-Za-z0-9_-]+$/
const refuse = (reason: string): never => { throw new HookPreparationHeld(`a hook argument ${reason}`) }

/**
 * [argv] as [runner] takes it: the list itself for `argv`; for the others, one line that [runner] splits back into
 * exactly these arguments. Words (`--port`, `18473`, `codex`) stay bare and everything else is quoted, so the POSIX
 * line is byte for byte what every release wrote. An argument a runner would read as anything but itself is refused,
 * never escaped. The line holds only Harness's own paths and flags, so a path with such a character holds the hook
 * install with a reason.
 */
export function quoteHookCommand(runner: HookRunner, argv: string[]): string | string[] {
  if (!argv.length) refuse('list is empty')
  for (const arg of argv) {
    if (typeof arg !== 'string') refuse('is not text')
    if (/[\0\r\n]/.test(arg)) refuse('holds a line break or NUL, which no hook runner passes whole')
  }
  switch (runner) {
    case 'argv': return [...argv]
    case 'bash': return argv.map((arg) => BARE_WORD.test(arg) ? arg : shellQuote(arg)).join(' ')
    case 'cmd': return argv.map(withoutTrailingSeparators).map((arg) => {
      // cmd.exe expands %…% (and !…! with delayed expansion) even inside quotes, and a quote ends them. `& | < > ^ ( )`
      // are refused too, in case an engine does not wrap the line: unquoted, cmd.exe reads them as its own syntax. A
      // trailing backslash would escape the closing quote for the program's own parser (CommandLineToArgvW's rules).
      if (/["%!&|<>^()]/.test(arg)) refuse('holds one of " % ! & | < > ^ ( ), which cmd.exe reads as more than text')
      if (arg.endsWith('\\')) refuse('ends in a backslash, which would escape its closing quote')
      return BARE_WORD.test(arg) ? arg : `"${arg}"`
    }).join(' ')
    case 'powershell': return `& ${argv.map(withoutTrailingSeparators).map((arg) => {
      // Inside single quotes PowerShell reads only a quote, typographic ones too. Windows PowerShell 5.1 passes a
      // double quote inside an argument to a native program unescaped.
      if (arg === '') refuse('is empty, which Windows PowerShell 5.1 drops')
      if (arg.endsWith('\\')) refuse('ends in a backslash, which would escape its closing quote')
      if (/["\u2018\u2019\u201a\u201b]/.test(arg)) refuse('holds a double or typographic quote, which PowerShell passes on differently')
      return BARE_WORD.test(arg) ? arg : `'${arg.replace(/'/g, "''")}'`
    }).join(' ')}`
  }
}

/**
 * A Windows folder without its trailing backslashes, which name the same folder: `CODEX_HOME=C:\codex\`, as the
 * environment dialog takes a folder, turned that engine's hooks off as "ends in a backslash" (final review R2-3). A root
 * (`C:\`, `\\server\share\`) has nothing to drop, and anything that is not an absolute path is left as it is.
 */
function withoutTrailingSeparators(arg: string): string {
  if (!win32.isAbsolute(arg)) return arg
  const root = win32.parse(arg).root
  let end = arg.length
  while (end > root.length && arg[end - 1] === '\\') end--
  return arg.slice(0, end)
}

type NotifyEngine = 'claude' | 'codex' | 'cursor' | 'hermes' | 'commandcode' | 'devin' | 'grok' | 'agy' | 'copilot'

/** notify.mjs's argument list for [engine]: the managed Node, the script, and Harness's own flags. No user input. */
export function hookArgv(
  port: number,
  engine: NotifyEngine,
  // Only ever non-default for 'codex': a per-agent CODEX_HOME profile gets its OWN hooks.json, and
  // that file's baked --codex-home must match where it actually lives (see installCodexHooks).
  codexHome: string = env.CODEX_HOME,
  // Same rule for Hermes, and it was broken the same way: a `hermes -p <name>` profile has its own
  // config.yaml, and the block in it carried the DEFAULT home — so the hook looked the session up in
  // a store it was not in (openharness#191). See installHermesHooks.
  hermesHome: string = env.HERMES_HOME,
  environment?: Readonly<Record<string, string>>,
): string[] {
  const homes = environment ? nativeHookLocations(environment) : { ...env, CURSOR_HOME: cursorDataDir() }
  return [
    // Absolute, never the bare word `node`. This string is executed later by the ENGINE, in a shell
    // whose PATH is none of our business — and since the product ships its own Node, a computer with
    // no `node` on PATH is normal. See managedNodePath(); a changed interpreter is picked up by the
    // same drift comparison each installer already does for a changed path or port.
    managedNodePath(),
    HOOK_SCRIPT,
    '--port', String(port),
    '--data-dir', env.ADAPTER_DATA_DIR,
    '--claude-projects-dir', homes.CLAUDE_PROJECTS_DIR,
    '--codex-home', environment ? homes.CODEX_HOME : codexHome,
    '--grok-home', homes.GROK_HOME,
    '--cursor-home', homes.CURSOR_HOME,
    '--hermes-home', environment ? homes.HERMES_HOME : hermesHome,
    '--commandcode-home', homes.COMMANDCODE_HOME,
    '--devin-home', homes.DEVIN_HOME,
    '--agy-home', homes.AGY_HOME,
    '--copilot-home', homes.COPILOT_HOME,
    ...(engine !== 'claude' ? ['--engine', engine] : []),
  ]
}

/** The hook line for a shell runner: POSIX `bash` everywhere but Windows, where the caller names its engine's runner. */
export function command(
  port: number,
  engine: NotifyEngine,
  codexHome: string = env.CODEX_HOME,
  hermesHome: string = env.HERMES_HOME,
  environment?: Readonly<Record<string, string>>,
  runner: Exclude<HookRunner, 'argv'> = 'bash',
): string {
  return quoteHookCommand(runner, hookArgv(port, engine, codexHome, hermesHome, environment)) as string
}

/** The words of a POSIX shell line as `sh` splits it; null for anything but literal words. */
function posixWords(value: string): string[] | null {
  const args: string[] = []
  let word = '', active = false, quote = ''
  for (let index = 0; index < value.length; index++) {
    const char = value[index]
    if (quote) {
      if (char === quote) { quote = ''; continue }
      if (quote === '"' && /[$`\\]/.test(char)) return null
      word += char; continue
    }
    if (char === "'" || char === '"') { quote = char; active = true; continue }
    if (char === '\\') {
      if (++index === value.length || /[\r\n]/.test(value[index])) return null
      word += value[index]; active = true; continue
    }
    if (/[\r\n]/.test(char)) return null
    if (/[ \t]/.test(char)) { if (active) { args.push(word); word = ''; active = false }; continue }
    if (/[;&|<>$`(){}*?\[\]~#]/.test(char)) return null
    word += char; active = true
  }
  if (quote) return null
  if (active) args.push(word)
  return args
}

// Exactly what quoteHookCommand writes: it refuses the characters excluded here, a trailing backslash (cmd, PowerShell)
// and an empty argument (PowerShell), so a line holding one was written by somebody else.
const CMD_WORD = /"([^"%!&|<>^()]*)"|([A-Za-z0-9_-]+)/y
const POWERSHELL_WORD = /'((?:[^'"\u2018\u2019\u201a\u201b]|'')+)'|([A-Za-z0-9_-]+)/y

/** Words separated by one space, each matching [word] whole; null otherwise. */
function separatedWords(text: string, word: RegExp, unquote: (quoted: string) => string): string[] | null {
  const words: string[] = []
  let at = 0
  while (at < text.length) {
    if (words.length) { if (text[at] !== ' ') return null; at++ }
    word.lastIndex = at
    const match = word.exec(text)
    if (!match) return null
    const quoted = match[1] !== undefined
    if (quoted && /\\$/.test(unquote(match[1]))) return null
    words.push(quoted ? unquote(match[1]) : match[2])
    at = word.lastIndex
  }
  return words.length ? words : null
}

/** The words of a Windows hook line as quoteHookCommand writes it: cmd.exe's (`"…"`) or PowerShell's (`& '…'`). */
function windowsWords(value: string): string[] | null {
  if (/[\0\r\n]/.test(value)) return null
  if (value.startsWith('& ')) return separatedWords(value.slice(2), POWERSHELL_WORD, (quoted) => quoted.replace(/''/g, "'"))
  return separatedWords(value, CMD_WORD, (quoted) => quoted)
}

const LEGACY_SCRIPT = /\/\.harness\/cli\/(?:hook\/)?notify\.mjs$/
const NODE = /^(?:node|nodejs)(?:\.exe)?$/
const WINDOWS_NODE = /^(?:node|nodejs)(?:\.exe)?$/i
// POSIX path rules for a POSIX-quoted line on every host: on Windows, `C:\…` inside sh quotes is no line Harness writes,
// and the win32 rules took a person's look-alike for Harness's (carried B4.2, final review R2-1).
const POSIX_LINE_PATH = { basename: posix.basename, isAbsolute: posix.isAbsolute }

/** Harness's protocol: a literal Node, an absolute notify.mjs, and only Harness's flags, each once. */
function managedArgs(args: string[], path: Pick<typeof win32, 'basename' | 'isAbsolute'>, node: RegExp, legacy: boolean): boolean {
  if (!node.test(path.basename(args[0] ?? '')) || !path.isAbsolute(args[1] ?? '') || path.basename(args[1] ?? '') !== 'notify.mjs') return false
  // The original positional protocol was installed only under Harness's own
  // CLI directory. Later commands identify the data root explicitly.
  if (legacy && args.length === 4 && LEGACY_SCRIPT.test(args[1])
    && /^\d+$/.test(args[2]) && /^(?:claude|codex)$/.test(args[3])) return true
  const flags = new Map<string, string>()
  for (let index = 2; index < args.length; index += 2) {
    const key = args[index], value = args[index + 1]
    if (!/^--(?:port|data-dir|claude-projects-dir|(?:codex|grok|cursor|hermes|commandcode|devin|agy|copilot)-home|engine|event|agy-event|copilot-event)$/.test(key)
      || value === undefined || flags.has(key)) return false
    flags.set(key, value)
  }
  return /^\d+$/.test(flags.get('--port') ?? '') && path.isAbsolute(flags.get('--data-dir') ?? '')
}

/** Accept only a literal Node invocation with Harness's protocol arguments.
 * A foreign script sharing the notify.mjs basename is not ours to remove. On Windows, the cmd.exe and PowerShell
 * lines quoteHookCommand writes are literal invocations too. */
export function isManagedHookCommand(value: unknown, platform: NodeJS.Platform = process.platform): boolean {
  if (typeof value !== 'string' || value.length > 64 * 1024) return false
  const words = posixWords(value)
  if (words && managedArgs(words, POSIX_LINE_PATH, NODE, true)) return true
  if (platform !== 'win32') return false
  const windows = windowsWords(value)
  return !!windows && managedArgs(windows, win32, WINDOWS_NODE, false)
}

/** One hook of an engine's settings: a line, or on Windows exec form (Claude Code's `command` + `args`). */
export function isManagedHook(hook: { type?: unknown; command?: unknown; args?: unknown } | null | undefined, platform: NodeJS.Platform = process.platform): boolean {
  if (!hook || typeof hook !== 'object') return false
  // On win32 any `args` key (even `[]`) sends a hook to the exec-form check, so a line-form hook with a stray `args` is not ours: the safe direction.
  if (hook.args === undefined || platform !== 'win32') return isManagedHookCommand(hook.command, platform)
  return typeof hook.command === 'string' && Array.isArray(hook.args) && hook.args.length <= 64
    && hook.args.every((arg) => typeof arg === 'string' && !/[\0\r\n]/.test(arg))
    && managedArgs([hook.command, ...hook.args as string[]], win32, WINDOWS_NODE, false)
}

export function isOurs(block: HookBlock, platform: NodeJS.Platform = process.platform): boolean {
  return Array.isArray(block?.hooks) && block.hooks.some(hook => isManagedHook(hook, platform))
}

/** A managed command can share a block with somebody else's command. Updating
 * ours must keep those siblings and the block's matcher and other fields. */
export function foreignHookBlocks(blocks: HookBlock[], owns: (block: HookBlock) => boolean = isOurs): HookBlock[] {
  for (const block of blocks) {
    if (!block || typeof block !== 'object' || !Array.isArray(block.hooks) || block.hooks.some(hook =>
      !hook || typeof hook !== 'object' || (hook.command !== undefined && typeof hook.command !== 'string'))) {
      throw new HookPreparationHeld('a hook block has an unconfirmed shape')
    }
  }
  return blocks.flatMap(block => {
    if (!owns(block)) return [block]
    const hooks = block.hooks.filter(hook => !owns({ hooks: [hook] }))
    return hooks.length ? [{ ...block, hooks }] : []
  })
}