Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
22.7 KB
Raw Blame
/**
 * `gbrain wakeshift enable | disable | status | test | cron | emit` (plan D2,
 * D4, D5): the trusted local switch for reporting back through Wakeshift.
 * Only this command writes the `wakeshift.*` keys (host file plane), so no
 * MCP or HTTP caller can turn it on. `enable` asks consent (egress,
 * credentials), requires the operator's terms and privacy links on a brain
 * with live access members, checks the key with GET /app, merges the event
 * manifest and stores its hash; `disable` hides the watch tools at once and
 * ends open watches; `status` and `test` show the key's kid fingerprint,
 * never the key, and `status` says when the published manifest is older than
 * this build. `cron add|remove|list` keeps the names watch_cron accepts;
 * `emit cron.finished` records a run for the drainer and never calls
 * Wakeshift or fails the cron script. Guide: docs/guides/wakeshift.md.
 */
import { readFileSync, renameSync, writeFileSync } from 'node:fs';
import type { BrainEngine } from '../core/engine.ts';
import { loadConfig, loadConfigFileOnly, saveConfig, type GBrainConfig } from '../core/config.ts';
import { managedFilesystemDatastorePath } from '../core/persistence/filesystem-guard.ts';
import { SPOOL_MAX_FILES, ingestCronSpool, recordCronRun, spoolCronRun } from '../core/wakeshift/spool.ts';
import { opError } from '../core/ops/contract.ts';
import { requireConsent } from '../core/consent.ts';
import { WakeshiftError, WakeshiftKeyError, normalizeWakeshiftUrl, parseWakeshiftKey, wakeshiftClient, type WakeshiftKey } from '../core/wakeshift/client.ts';
import { readWakeshiftKey, wakeshiftFileConfig, wakeshiftKeyFile, wakeshiftPublished, wakeshiftRuntime, wakeshiftSecret, type WakeshiftFileConfig } from '../core/wakeshift/config.ts';
import { CRON_FINISHED, cronName, wakeshiftManifest, wakeshiftManifestHash } from '../core/wakeshift/events.ts';
import { endAtWakeshift, liveAccessMembers } from '../core/wakeshift/drain.ts';
import { WAKESHIFT_CONNECTOR_TERMS_URL, WAKESHIFT_PRIVACY_URL, httpsUrl, operatorTerms } from '../core/wakeshift/terms.ts';
import { setCliExitVerdict } from '../core/cli-force-exit.ts';
import { shellQuote } from '../core/agent-output.ts';

const HELP = `gbrain wakeshift <command> — report back to agent conversations when jobs, writes and crons finish (off by default)

Commands:
  status [--json]            on/off, where the key comes from (its kid fingerprint only), watch counts,
                             and whether the published manifest is older than this build
  enable [--key-stdin] [--url <https url>] [--terms-url <https url> --privacy-url <https url>] [--yes]
                             turn reporting back on: asks consent, checks the key with Wakeshift and
                             publishes gbrain's events; --key-stdin saves the key from stdin to
                             ~/.gbrain/wakeshift.key (0600). A brain with access members needs your
                             terms and privacy links; each member accepts them before a first watch
  disable [--json]           turn it off: the watch tools disappear at once and open watches end
  test [--json]              check the key and the app with Wakeshift; sends no wake
  cron add <name> | remove <name> | list [--json]
                             the cron names agents may watch with watch_cron
  emit cron.finished --name <name> --status ok|failed
                             record a cron run at the end of the cron's script; the drainer wakes its
                             watchers. Never calls Wakeshift itself, and exits 0 when reporting back is off
  watch job <id> | write <request_id> | cron <name>
                             from a thin client or agent shell: wake this conversation when it finishes
                             (gbrain wakeshift watch --help)
  accept-terms <terms_version>
                             from a thin client or agent shell: record the user's agreement to a shared
                             brain's agreement step (accept_wakeshift_terms), then run the watch again

The key is read from WAKESHIFT_API_KEY (e.g. in ~/.gbrain/.env) or ~/.gbrain/wakeshift.key.
gbrain never creates a Wakeshift account or key. Guide: docs/guides/wakeshift.md`;

function flagValue(args: string[], flag: string): string | undefined {
  const i = args.indexOf(flag);
  return i >= 0 && args[i + 1] && !args[i + 1]!.startsWith('--') ? args[i + 1] : undefined;
}

const KEY_HINT = 'Create a key in your Wakeshift console and put it in ~/.gbrain/wakeshift.key (chmod 600) or WAKESHIFT_API_KEY in ~/.gbrain/.env, then run gbrain wakeshift enable again.';

function keyError(reason: string, message: string, suggestion: string): Error {
  return opError('wakeshift_key_invalid', message, suggestion, { reason });
}

/** The configured key, parsed, or a wakeshift_key_invalid error that names what to do. */
function loadKey(): { key: WakeshiftKey; source: 'env' | 'file' } {
  const read = readWakeshiftKey();
  if (read.source === 'file_too_open') {
    throw keyError('file_too_open', `${wakeshiftKeyFile()} is readable by other users (mode ${read.mode}).`, `Run chmod 600 ${wakeshiftKeyFile()}, then run gbrain wakeshift enable again.`);
  }
  if (read.source === 'none') throw keyError('missing', 'No Wakeshift key: set WAKESHIFT_API_KEY (in ~/.gbrain/.env) or write ~/.gbrain/wakeshift.key.', KEY_HINT);
  try {
    return { key: parseWakeshiftKey(read.raw), source: read.source };
  } catch (e) {
    if (e instanceof WakeshiftKeyError) throw keyError(e.reason, e.message, KEY_HINT);
    throw e;
  }
}

async function watchCounts(engine: BrainEngine): Promise<Record<string, number>> {
  try {
    const rows = await engine.executeRaw<{ state: string; last_error: string | null; n: number }>(
      'SELECT state, last_error, count(*)::int AS n FROM wake_subscriptions GROUP BY state, last_error');
    const out: Record<string, number> = { open: 0, delivered: 0, dead: 0, ended: 0, id_reused: 0 };
    for (const r of rows) {
      out[r.state] = (out[r.state] ?? 0) + Number(r.n);
      if (r.last_error === 'id_reused') out.id_reused! += Number(r.n);
    }
    return out;
  } catch {
    return {};
  }
}

function writeFilePlane(update: (w: WakeshiftFileConfig) => WakeshiftFileConfig): void {
  const cfg = (loadConfigFileOnly() ?? { engine: 'pglite' }) as GBrainConfig & { wakeshift?: WakeshiftFileConfig };
  cfg.wakeshift = update({ ...(cfg.wakeshift ?? {}) });
  saveConfig(cfg);
}

function say(json: boolean, doc: Record<string, unknown>, lines: string[]): void {
  if (json) console.log(JSON.stringify(doc, null, 2));
  else for (const l of lines) console.log(l);
}

function describeWakeshiftError(e: unknown): string {
  return e instanceof WakeshiftError ? `${e.code} (HTTP ${e.status || 'none'}): ${e.message}` : String(e instanceof Error ? e.message : e);
}

async function status(engine: BrainEngine, json: boolean): Promise<void> {
  const file = wakeshiftFileConfig(loadConfigFileOnly());
  const read = readWakeshiftKey();
  let kid: string | null = null;
  let keyProblem: string | null = read.source === 'file_too_open' ? `key file mode ${read.mode} (must be 0600)` : read.source === 'none' ? 'no key' : null;
  if (read.source === 'env' || read.source === 'file') {
    try { kid = parseWakeshiftKey(read.raw).kid; } catch (e) { keyProblem = (e as Error).message; }
  }
  const counts = await watchCounts(engine);
  const on = file.enabled === true && kid !== null;
  const manifestStale = file.enabled === true && file.manifest_hash !== wakeshiftManifestHash();
  const terms = operatorTerms(file);
  say(json, {
    enabled: file.enabled === true, active: on, url: normalizeWakeshiftUrl(file.url), key: { source: read.source, kid, problem: keyProblem }, watches: counts,
    manifest: { current: !manifestStale, ...(manifestStale ? { fix: shellQuote(['gbrain', 'wakeshift', 'enable']) } : {}) },
    terms: terms ? { terms_url: terms.terms_url, privacy_url: terms.privacy_url, version: terms.version } : null,
  }, [
    `Wakeshift reporting back: ${on ? 'on' : file.enabled === true ? 'enabled but inactive' : 'off'}`,
    `  url:     ${normalizeWakeshiftUrl(file.url)}`,
    `  key:     ${kid ? `${read.source} (kid ${kid})` : keyProblem}`,
    `  watches: ${Object.entries(counts).map(([k, v]) => `${k} ${v}`).join(', ') || 'none'}`,
    ...(terms ? [`  terms:   ${terms.terms_url} and ${terms.privacy_url} (version ${terms.version})`] : []),
    ...(on || file.enabled !== true ? [] : ['  The watch tools stay hidden until the key problem above is fixed.']),
    ...(manifestStale ? ['  The published event manifest is older than this build: run gbrain wakeshift enable to publish the new events.'] : []),
  ]);
}

async function enable(engine: BrainEngine, args: string[]): Promise<void> {
  const stdinKey = args.includes('--key-stdin') ? readFileSync(0, 'utf8').trim() : null;
  let loaded: { key: WakeshiftKey; source: 'env' | 'file' | 'stdin' };
  if (stdinKey !== null) {
    if (readWakeshiftKey().source === 'env') {
      throw keyError('env_overrides', 'WAKESHIFT_API_KEY is set (in the environment or ~/.gbrain/.env) and takes precedence over a saved key, so --key-stdin would save a key gbrain never uses. Nothing was saved.',
        'Remove WAKESHIFT_API_KEY, then run gbrain wakeshift enable --key-stdin again; or run gbrain wakeshift enable without --key-stdin to use it.');
    }
    try { loaded = { key: parseWakeshiftKey(stdinKey), source: 'stdin' }; } catch (e) { if (e instanceof WakeshiftKeyError) throw keyError(e.reason, e.message, KEY_HINT); throw e; }
  } else {
    loaded = loadKey();
  }
  const { key, source } = loaded;
  const saved = wakeshiftFileConfig(loadConfigFileOnly());
  const links: Pick<WakeshiftFileConfig, 'terms_url' | 'privacy_url'> = {};
  for (const [flag, field] of [['--terms-url', 'terms_url'], ['--privacy-url', 'privacy_url']] as const) {
    const raw = flagValue(args, flag);
    if (raw === undefined) continue;
    const url = httpsUrl(raw);
    if (!url) throw opError('invalid_params', `${flag} must be an absolute https URL (got ${JSON.stringify(raw.slice(0, 80))}).`, `Pass the https address of your published ${field === 'terms_url' ? 'terms' : 'privacy policy'}.`);
    links[field] = url;
  }
  const terms = operatorTerms({ ...saved, ...links });
  const members = await liveAccessMembers(engine);
  if (members > 0 && !terms) {
    throw opError('wakeshift_shared_brain', `This brain has ${members} live access member(s), and Wakeshift's terms make you, the operator, show each of them your own terms and privacy policy before any wake. Nothing was turned on.`,
      'Run gbrain wakeshift enable --terms-url <https url> --privacy-url <https url> with your published terms and privacy policy (they must refer members to Wakeshift\'s Connector Terms and Privacy Policy); each member then accepts them once before a first watch.');
  }
  const url = normalizeWakeshiftUrl(flagValue(args, '--url') ?? saved.url);
  const operatorDuty = members > 0
    ? ` This brain has ${members} access member(s): as the operator you are the controller of their wake data and Wakeshift is your processor (its DPA). Your terms (${terms!.terms_url}) and privacy policy (${terms!.privacy_url}) must refer members to Wakeshift's Connector Terms (${WAKESHIFT_CONNECTOR_TERMS_URL}) and Privacy Policy (${WAKESHIFT_PRIVACY_URL}), incorporate them and name Clawvisor Inc. as a third-party beneficiary (Wakeshift ToS 6.6), state a minimum age for members, and say that wakes pass through Wakeshift. Each member accepts your terms once before a first watch.`
    : '';
  await requireConsent({
    command: 'wakeshift enable', effects: ['egress', 'credentials'], actor: 'user',
    what: `Turn on reporting back through Wakeshift (${url}) with the key kid ${key.kid}.`,
    why: 'Agents can then ask gbrain to wake their conversation when a job, a pending write or a scheduled cron finishes, instead of polling.',
    risk: `Each watched job, write request or cron sends Wakeshift a pointer: its id or cron name, kind, status, times, a hashed user id, the MCP client name, user agent and request _meta. Never page text, titles or slugs. Members of your Wakeshift organization can read sent wakes.${operatorDuty}`,
    user_message: `Turn on gbrain reporting back through Wakeshift? It sends ids and status (never page text) to Wakeshift when a watched job, write or cron finishes.${members > 0 ? ' This brain has members, so your terms and privacy policy must refer them to Wakeshift\'s Connector Terms and Privacy Policy.' : ''}`,
    argv: ['gbrain', 'wakeshift', 'enable'], args,
  });
  const api = wakeshiftClient(key, { url });
  let app;
  try {
    app = await api.getApp();
    await api.mergeManifest(wakeshiftManifest());
  } catch (e) {
    throw opError(e instanceof WakeshiftError && (e.status === 0 || e.status === 429 || e.status >= 500) ? 'wakeshift_unavailable' : 'wakeshift_refused',
      `Wakeshift did not accept the key or the manifest: ${describeWakeshiftError(e)}. Nothing was turned on.`,
      'Check the key belongs to your Wakeshift app (gbrain wakeshift test) and retry.', { reason: e instanceof WakeshiftError ? e.code : 'error' });
  }
  if (stdinKey !== null) {
    const tmp = `${wakeshiftKeyFile()}.${process.pid}.tmp`;
    writeFileSync(tmp, stdinKey + '\n', { mode: 0o600, flag: 'wx' });
    renameSync(tmp, wakeshiftKeyFile());
    console.error(`[wakeshift] saved the key to ${wakeshiftKeyFile()} (0600).`);
  }
  wakeshiftSecret();
  writeFilePlane(w => {
    const next: WakeshiftFileConfig = { ...w, ...links, enabled: true, url, manifest_hash: wakeshiftManifestHash() };
    if (url === 'https://app.wakeshift.ai') delete next.url;
    return next;
  });
  say(args.includes('--json'), { enabled: true, url, app: { id: app?.id, name: app?.name }, key: { source, kid: key.kid }, ...(terms ? { terms_version: terms.version } : {}) }, [
    `Wakeshift reporting back is on (app ${app?.name ?? '?'}, key kid ${key.kid}, from ${source}).`,
    'Agents now see watch_job, watch_write_request, watch_cron, list_watches and unwatch; gbrain serve and the job worker deliver wakes.',
    ...(members > 0 ? [`Members see your terms (version ${terms!.version}) on their first watch and accept them with accept_wakeshift_terms; changing a link asks again.`] : []),
    'Turn it off with: gbrain wakeshift disable',
  ]);
}

async function disable(engine: BrainEngine, json: boolean): Promise<void> {
  writeFilePlane(w => ({ ...w, enabled: false }));
  const rows = await engine.executeRaw<{ id: number; wake_user: string; ws_subscription_id: string }>(
    `UPDATE wake_subscriptions SET state = 'ended', last_error = 'disabled', lease_until = NULL, updated_at = now() WHERE state = 'open'
     RETURNING id, wake_user, ws_subscription_id`);
  let told = 0;
  if (rows.length > 0) {
    try {
      const { key } = loadKey();
      const api = wakeshiftClient(key, { url: normalizeWakeshiftUrl(wakeshiftFileConfig(loadConfigFileOnly()).url) });
      for (const row of rows) if (await endAtWakeshift(api, row)) told++;
    } catch { /* no usable key: Wakeshift's own ttl ends them */ }
  }
  say(json, { enabled: false, ended: rows.length, told_wakeshift: told }, [
    'Wakeshift reporting back is off: the watch tools are hidden from the next tools/list.',
    `Ended ${rows.length} open watch(es)${rows.length ? ` (${told} confirmed by Wakeshift)` : ''}.`,
  ]);
}

async function test(json: boolean): Promise<void> {
  const { key, source } = loadKey();
  const url = normalizeWakeshiftUrl(wakeshiftFileConfig(loadConfigFileOnly()).url);
  try {
    const app = await wakeshiftClient(key, { url }).getApp();
    say(json, { ok: true, url, app: { id: app.id, name: app.name }, key: { source, kid: key.kid, key_id: app.key?.key_id } }, [
      `ok: Wakeshift accepted the key (app ${app.name}, key ${app.key?.name ?? app.key?.key_id ?? '?'}, kid ${key.kid}).`,
    ]);
  } catch (e) {
    say(json, { ok: false, url, key: { source, kid: key.kid }, error: describeWakeshiftError(e) }, [`fail: ${describeWakeshiftError(e)}`]);
    setCliExitVerdict(1);
  }
}

/** `cron add|remove|list`: the names watch_cron accepts (slugged to [a-z0-9._-], at most 64). Local state; works with reporting back off. */
async function cron(engine: BrainEngine, args: string[], json: boolean): Promise<void> {
  const [verb, raw] = args;
  if (verb === 'list') {
    const rows = await engine.executeRaw<{ name: string; created_at: Date | string; last_status: string | null; last_finished_at: Date | string | null }>(
      `SELECT c.name, c.created_at, r.status AS last_status, r.finished_at AS last_finished_at FROM wake_crons c
        LEFT JOIN LATERAL (SELECT status, finished_at FROM wake_cron_runs WHERE name = c.name ORDER BY finished_at DESC, id DESC LIMIT 1) r ON true
        ORDER BY c.name`);
    say(json, { crons: rows }, rows.length ? rows.map(r => `${r.name}${r.last_status ? `  last run: ${r.last_status} at ${new Date(r.last_finished_at!).toISOString()}` : '  no run reported yet'}`) : ['No crons registered (gbrain wakeshift cron add <name>).']);
    return;
  }
  const name = cronName(raw);
  if ((verb !== 'add' && verb !== 'remove') || !name) {
    console.error('Usage: gbrain wakeshift cron add <name> | remove <name> | list [--json]');
    setCliExitVerdict(2);
    return;
  }
  const renamed = name !== raw ? ` (stored as ${name})` : '';
  if (verb === 'add') {
    await engine.executeRaw('INSERT INTO wake_crons (name) VALUES ($1) ON CONFLICT (name) DO NOTHING', [name]);
    say(json, { name, registered: true }, [`Registered cron ${name}${renamed}. End its script with: gbrain wakeshift emit cron.finished --name ${name} --status ok (or failed).`]);
    return;
  }
  await engine.executeRaw('DELETE FROM wake_crons WHERE name = $1', [name]);
  const ended = await engine.executeRaw<{ id: number; wake_user: string; ws_subscription_id: string }>(
    `UPDATE wake_subscriptions SET state = 'ended', last_error = 'cron_removed', lease_until = NULL, updated_at = now()
      WHERE state = 'open' AND event = $1 AND target = $2 RETURNING id, wake_user, ws_subscription_id`, [CRON_FINISHED, name]);
  const api = ended.length ? wakeshiftRuntime()?.api : undefined;
  if (api) for (const row of ended) await endAtWakeshift(api, row);
  say(json, { name, registered: false, ended: ended.length }, [`Removed cron ${name}${renamed}; ended ${ended.length} open watch(es) on it.`]);
}

/**
 * `emit cron.finished --name <name> --status ok|failed`: record the run for the drainer and return. Never calls
 * Wakeshift and exits 0 whatever happens after the arguments parse (off, unregistered, a database error), with one
 * stderr line, so the cron script's own exit status stays its own.
 */
function emitArgs(args: string[]): { name: string; status: 'ok' | 'failed' } | null {
  const name = cronName(flagValue(args, '--name'));
  const status = flagValue(args, '--status');
  if (args[0] === 'cron.finished' && name && (status === 'ok' || status === 'failed')) return { name, status };
  console.error('Usage: gbrain wakeshift emit cron.finished --name <name> --status ok|failed');
  setCliExitVerdict(2);
  return null;
}

/** The datastore path of the PGLite brain this CLI resolved (`brainId` names a mount), or null for Postgres. */
async function pgliteDatastore(brainId: string | undefined): Promise<string | null> {
  if (brainId && brainId !== 'host') {
    const mount = (await import('../core/brain-registry.ts')).loadMounts().find(m => m.id === brainId);
    return mount?.engine === 'pglite' ? mount.database_path ?? null : null;
  }
  const config = loadConfig();
  return config?.engine === 'pglite' ? config.database_path ?? null : null;
}

/**
 * The brain could not be opened for `emit`. On a PGLite brain held by `gbrain serve` or `gbrain jobs work`, the run
 * goes to the brain's spool (spool.ts) for that process's wake drainer to record; otherwise (Postgres, reporting back
 * off, a full spool) it is not recorded. Either way one stderr line, and the cron script keeps its own exit status.
 */
export async function reportEmitConnectFailure(args: string[], error: unknown, brainId?: string): Promise<null> {
  const parsed = emitArgs(args);
  if (!parsed) return null;
  const reason = error instanceof Error ? error.message.split('\n')[0] : String(error);
  try {
    const datastore = await pgliteDatastore(brainId);
    if (datastore && wakeshiftPublished()) {
      const spooled = spoolCronRun(datastore, parsed);
      if (spooled !== 'full') {
        console.error(`[wakeshift] the brain could not be opened (${reason}), so the ${parsed.name} run was spooled: the wake drainer of gbrain serve or gbrain jobs work records it within seconds.`);
        return null;
      }
      console.error(`[wakeshift] could not record the ${parsed.name} run: ${SPOOL_MAX_FILES} runs already wait in the spool, which only gbrain serve or gbrain jobs work drains.`);
      return null;
    }
  } catch (e) {
    console.error(`[wakeshift] could not spool the ${parsed.name} run: ${e instanceof Error ? e.message : String(e)}`);
    return null;
  }
  console.error(`[wakeshift] could not record the ${parsed.name} run: the brain could not be opened (${reason}).`);
  return null;
}

async function emit(engine: BrainEngine, args: string[]): Promise<void> {
  const parsed = emitArgs(args);
  if (!parsed) return;
  const { name, status } = parsed;
  if (!wakeshiftPublished()) {
    console.error(`[wakeshift] reporting back is off, so the ${name} run was not recorded (gbrain wakeshift status).`);
    return;
  }
  try {
    const datastore = managedFilesystemDatastorePath(engine);
    if (datastore) await ingestCronSpool(engine, datastore).catch(e => console.error(`[wakeshift] could not take the spooled cron runs: ${e instanceof Error ? e.message : String(e)}`));
    await recordCronRun(engine, { name, status });
  } catch (e) {
    console.error(`[wakeshift] could not record the ${name} run: ${e instanceof Error ? e.message : String(e)}`);
  }
}

/** `gbrain config get mcp.publish_wakeshift`: the runtime gate, which never reads the DB plane. */
export function printWakeshiftGate(): void {
  console.log(String(wakeshiftPublished()));
  console.error('[config] source: wakeshift.enabled in the host file plane plus a usable Wakeshift key; the DB plane is never read for this gate (gbrain wakeshift status)');
}

export async function runWakeshift(engine: BrainEngine, args: string[]): Promise<void> {
  const sub = args[0];
  const json = args.includes('--json');
  if (sub === 'watch' || sub === 'accept-terms') return (await import('./wakeshift-watch.ts')).runWakeshiftWatch(engine, sub === 'watch' ? args.slice(1) : args);
  if (!sub || args.includes('--help') || args.includes('-h')) { console.log(HELP); return; }
  if (sub === 'status') return status(engine, json);
  if (sub === 'enable') return enable(engine, args.slice(1));
  if (sub === 'disable') return disable(engine, json);
  if (sub === 'test') return test(json);
  if (sub === 'cron') return cron(engine, args.slice(1), json);
  if (sub === 'emit') return emit(engine, args.slice(1));
  console.error(`Unknown wakeshift command: ${sub}\n\n${HELP}`);
  setCliExitVerdict(2);
}