Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.7 KB
Raw Blame
/**
 * openclaw-turn-plugin.ts — OpenClaw's native per-turn hook for the
 * brain-first rule: a hook-only OpenClaw plugin whose `before_prompt_build`
 * handler returns the rule as `prependContext`, so it reaches the model next
 * to each user turn (without its reply sentence on `internal_system` turns).
 * The workspace AGENTS.md block reaches the system prompt only, and bots read
 * it as identity, not as an instruction to call a tool.
 *
 * The plugin is self-contained (the rule text is written into its code; it
 * reads nothing and calls nothing) and lives in <OpenClaw state dir>/gbrain/.
 * Setup installs it with OpenClaw's own CLI, the supported path: a linked
 * install with capability consent, enabled, and
 * `plugins.entries.gbrain-turn-rule.hooks.allowConversationAccess`, which
 * OpenClaw requires of a non-bundled plugin's `before_prompt_build`. With no
 * `openclaw` on PATH, setup writes the plugin and prints those commands.
 */
import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { atomicWriteTextFile } from '../bootstrap/atomic-write.ts';
import { bunSpawnSync } from '../spawn.ts';
import { openclawStateDir, renderBrainFirstTurnRule, type BrainFirstAccess } from './brain-first.ts';

export const OPENCLAW_TURN_PLUGIN_ID = 'gbrain-turn-rule';

export interface OpenclawTurnPluginOutcome { action: 'write' | 'keep' | 'print' | 'remove' | 'skip'; path: string; detail: string; commands?: string[] }

export function openclawTurnPluginDir(): string {
  return join(openclawStateDir(), 'gbrain', OPENCLAW_TURN_PLUGIN_ID);
}

const DESCRIPTION = 'Puts the GBrain brain-first rule next to every user turn (managed by gbrain setup openclaw).';

export function openclawTurnPluginFiles(access: BrainFirstAccess): Record<string, string> {
  const rule = renderBrainFirstTurnRule(access, 'openclaw');
  return {
    'package.json': `${JSON.stringify({ name: OPENCLAW_TURN_PLUGIN_ID, version: '1.0.0', private: true, type: 'module', openclaw: { extensions: ['./index.js'] }, gbrain: { access } }, null, 2)}\n`,
    'openclaw.plugin.json': `${JSON.stringify({ id: OPENCLAW_TURN_PLUGIN_ID, name: 'GBrain turn rule', description: DESCRIPTION, configSchema: { type: 'object', additionalProperties: false } }, null, 2)}\n`,
    'index.js': [
      '// Managed by gbrain setup openclaw; a re-run rewrites this file. Remove: gbrain setup openclaw --remove',
      `const RULE = ${JSON.stringify(rule)};`,
      `const INTERNAL_RULE = ${JSON.stringify(renderBrainFirstTurnRule(access, 'openclaw', { reply: false }))};`,
      'export default {',
      `  id: ${JSON.stringify(OPENCLAW_TURN_PLUGIN_ID)},`,
      "  name: 'GBrain turn rule',",
      `  description: ${JSON.stringify(DESCRIPTION)},`,
      '  register(api) {',
      "    api.on('before_prompt_build', (_event, ctx) => ({ prependContext: ctx?.inputProvenance?.kind === 'internal_system' ? INTERNAL_RULE : RULE }));",
      '  },',
      '};',
      '',
    ].join('\n'),
  };
}

type Run = (argv: string[]) => { ok: boolean; output: string };

function defaultRun(argv: string[]): { ok: boolean; output: string } {
  const r = bunSpawnSync(argv, { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe', env: process.env, timeout: 120_000 });
  return { ok: r.exitCode === 0, output: `${r.stdout.toString()}${r.stderr.toString()}`.trim() };
}

function findOpenclaw(): string | null {
  try { return Bun.which('openclaw', { PATH: process.env.PATH ?? '' }); } catch { return null; }
}

const installArgv = (bin: string, dir: string): string[][] => [
  [bin, 'plugins', 'install', '--link', dir, '--force', '--accept-capabilities'],
  [bin, 'plugins', 'enable', OPENCLAW_TURN_PLUGIN_ID],
  [bin, 'config', 'set', `plugins.entries.${OPENCLAW_TURN_PLUGIN_ID}.hooks.allowConversationAccess`, 'true'],
];

const shown = (argv: string[]) => argv.map((a) => (/^[\w./:=@-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`)).join(' ');

/**
 * What an installed plugin was written for: the access its package.json records, else (an older gbrain recorded
 * none) the server or launcher its RULE literal names. undefined with no plugin, null when neither can be read.
 */
function installedAccess(dir: string): { access: BrainFirstAccess; recorded: boolean } | null | undefined {
  if (!existsSync(join(dir, 'index.js'))) return undefined;
  try {
    const recorded = (JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { gbrain?: { access?: BrainFirstAccess } }).gbrain?.access;
    if (recorded) return { access: recorded, recorded: true };
    const literal = /^const RULE = (".*");$/m.exec(readFileSync(join(dir, 'index.js'), 'utf8'))?.[1];
    const rule = literal ? JSON.parse(literal) as string : '';
    const server = /on the `([^`]+)` MCP server/.exec(rule)?.[1];
    const launcher = /check GBrain first \(`(.+?) search "<names>"`/.exec(rule)?.[1];
    return server ? { access: { kind: 'mcp', server }, recorded: false } : launcher ? { access: { kind: 'cli', launcher }, recorded: false } : null;
  } catch { return null; }
}

const named = (a: BrainFirstAccess) => (a.kind === 'mcp' ? `the \`${a.server}\` MCP server` : `\`${a.launcher}\``);

/**
 * Write the plugin and install it with OpenClaw's CLI (accepted decision). Never throws. Every agent on the gateway gets
 * the plugin's rule, so a `workspace`-scoped run leaves an installed plugin whose rule would name another server (or
 * one it cannot read) and prints, unverified, the command that changes it for every agent.
 */
export function syncOpenclawTurnPlugin(opts: { access: BrainFirstAccess; dryRun: boolean; workspace?: string; openclawBin?: string | null; run?: Run }): OpenclawTurnPluginOutcome {
  const dir = openclawTurnPluginDir();
  const installed = opts.workspace ? installedAccess(dir) : undefined;
  const same = installed && (installed.recorded
    ? renderBrainFirstTurnRule(installed.access, 'openclaw') === renderBrainFirstTurnRule(opts.access, 'openclaw')
    : named(installed.access) === named(opts.access));
  if (installed !== undefined && !same) {
    return { action: 'print', path: dir, detail: `${dir} left as it is: every agent on this OpenClaw gateway gets its rule, which ${installed ? `names ${named(installed.access)}` : 'gbrain cannot read'}, so a --workspace run does not rewrite it. To change it for every agent, run this, then this setup again`, commands: [`gbrain setup openclaw --remove --workspace ${opts.workspace}`] };
  }
  const files = openclawTurnPluginFiles(opts.access);
  const bin = opts.openclawBin !== undefined ? opts.openclawBin : findOpenclaw();
  const commands = installArgv(bin ?? 'openclaw', dir);
  const changed = Object.entries(files).some(([name, text]) => {
    try { return readFileSync(join(dir, name), 'utf8') !== text; } catch { return true; }
  });
  if (opts.dryRun) return { action: changed ? 'write' : 'keep', path: dir, detail: `per-turn rule plugin ${OPENCLAW_TURN_PLUGIN_ID} (before_prompt_build) at ${dir}${bin ? ', installed with the openclaw CLI' : ''}` };
  try {
    if (changed) {
      mkdirSync(dir, { recursive: true });
      for (const [name, text] of Object.entries(files)) atomicWriteTextFile(join(dir, name), text, { freshMode: 0o644 });
    }
  } catch (e) {
    return { action: 'print', path: dir, detail: `the plugin could not be written to ${dir} (${(e as Error).message})` };
  }
  if (!bin) return { action: 'print', path: dir, detail: `plugin written to ${dir}; no openclaw on PATH, so run these on the OpenClaw host, then restart the gateway`, commands: commands.map(shown) };
  const run = opts.run ?? defaultRun;
  for (const [i, argv] of commands.entries()) {
    const r = run(argv);
    if (!r.ok) return { action: 'print', path: dir, detail: `\`${shown(argv)}\` failed (${r.output.split('\n').at(-1) ?? 'no output'}); run the rest yourself`, commands: commands.slice(i).map(shown) };
  }
  return { action: changed ? 'write' : 'keep', path: dir, detail: `per-turn rule plugin ${OPENCLAW_TURN_PLUGIN_ID} (before_prompt_build) at ${dir}, installed and enabled; restart the gateway if it is running` };
}

/**
 * Uninstall the plugin, then delete its directory (decline or --remove). Never throws. The directory stays
 * until the uninstall succeeds: `install --link` put it in plugins.load.paths, and OpenClaw refuses a config
 * whose load path is missing.
 */
export function removeOpenclawTurnPlugin(opts: { dryRun: boolean; workspace?: string; openclawBin?: string | null; run?: Run }): OpenclawTurnPluginOutcome {
  const dir = openclawTurnPluginDir();
  if (!existsSync(dir)) return { action: 'skip', path: dir, detail: `no per-turn rule plugin at ${dir}` };
  if (opts.workspace) return { action: 'skip', path: dir, detail: `${dir} left in place: every agent on this OpenClaw gateway gets its rule, so opting out one workspace does not remove it. Remove it for every agent with gbrain setup openclaw --remove --workspace ${opts.workspace}` };
  if (opts.dryRun) return { action: 'remove', path: dir, detail: `per-turn rule plugin ${OPENCLAW_TURN_PLUGIN_ID} at ${dir}` };
  const bin = opts.openclawBin !== undefined ? opts.openclawBin : findOpenclaw();
  const uninstall = [bin ?? 'openclaw', 'plugins', 'uninstall', OPENCLAW_TURN_PLUGIN_ID, '--force'];
  const r = bin ? (opts.run ?? defaultRun)(uninstall) : { ok: false, output: 'no openclaw on PATH' };
  if (!r.ok) return { action: 'print', path: dir, detail: `${dir} left in place (OpenClaw still loads it); ${r.output.split('\n').at(-1)}, so run this on the OpenClaw host, then delete ${dir}`, commands: [shown(uninstall)] };
  try {
    rmSync(dir, { recursive: true, force: true });
    if (readdirSync(dirname(dir)).length === 0) rmdirSync(dirname(dir));
  } catch { /* uninstalled; a leftover directory is no longer loaded */ }
  return { action: 'remove', path: dir, detail: `per-turn rule plugin ${OPENCLAW_TURN_PLUGIN_ID} uninstalled and ${dir} removed` };
}