Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.5 KB
Raw Blame
/**
 * The events gbrain offers Wakeshift (plan D2, D3): `gbrain.job.finished`, a
 * minion job reaching completed, failed, dead or cancelled;
 * `gbrain.write.settled`, a write request reaching committed, failed,
 * conflict or cancelled; `gbrain.cron.finished`, a registered cron's run
 * reported by `gbrain wakeshift emit`. Every event is personal (only the
 * named subscription gets an occurrence) and deleted on delivery. The payload is a pointer: ids, status,
 * kind, times and the exact next call. Never page text, titles or slugs, so a
 * wake cannot widen readable_by, folder rules or private pages; the agent's
 * follow-up read goes through gbrain's own access checks.
 */
import { createHash } from 'node:crypto';

export const JOB_FINISHED = 'gbrain.job.finished';
export const WRITE_SETTLED = 'gbrain.write.settled';
export const CRON_FINISHED = 'gbrain.cron.finished';

const JOB_PAYLOAD = {
  type: 'object',
  properties: {
    job: { type: 'integer', minimum: 1 },
    name: { type: 'string', maxLength: 100 },
    status: { type: 'string', enum: ['completed', 'failed', 'dead', 'cancelled', 'gone'] },
    started_at: { type: ['string', 'null'] },
    finished_at: { type: ['string', 'null'] },
    duration_ms: { type: ['integer', 'null'], minimum: 0 },
    next: { type: 'string', maxLength: 200 },
  },
  required: ['job', 'status', 'next'],
  additionalProperties: false,
} as const;

const TIME = { type: ['string', 'null'] } as const;

const WRITE_PAYLOAD = {
  type: 'object',
  properties: {
    request_id: { type: 'string', maxLength: 64 },
    state: { type: 'string', enum: ['committed', 'failed', 'conflict', 'cancelled', 'gone'] },
    operation: { type: ['string', 'null'], maxLength: 100 },
    source_id: { type: ['string', 'null'], maxLength: 100 },
    accepted_at: TIME,
    settled_at: TIME,
    next: { type: 'string', maxLength: 200 },
  },
  required: ['request_id', 'state', 'next'],
  additionalProperties: false,
} as const;

const CRON_PAYLOAD = {
  type: 'object',
  properties: {
    name: { type: 'string', maxLength: 64 },
    status: { type: 'string', enum: ['ok', 'failed'] },
    finished_at: TIME,
    next: { type: 'string', maxLength: 200 },
  },
  required: ['name', 'status', 'next'],
  additionalProperties: false,
} as const;

/** The manifest `gbrain wakeshift enable` merges (POST /manifest/merge); topic as the SDK would build it. */
export function wakeshiftManifest(): { events: Record<string, unknown>[] } {
  const event = (name: string, description: string, arg: string, argSchema: Record<string, unknown>, payload: unknown) => ({
    name, description,
    arguments: { type: 'object', properties: { [arg]: argSchema }, required: [arg], additionalProperties: false },
    payload, topic: `ev/${name}/{${arg}}`, personal: true, delete_on_delivery: true,
  });
  return {
    events: [
      event(JOB_FINISHED, 'A gbrain background job you are watching reached completed, failed, dead or cancelled. The payload is a pointer: call get_job with the id for the result.',
        'job', { type: 'integer', minimum: 1 }, JOB_PAYLOAD),
      event(WRITE_SETTLED, 'A gbrain write request you are watching reached committed, failed, conflict or cancelled. The payload is a pointer: call get_write_request with the id for the receipt.',
        'request_id', { type: 'string', pattern: '^[0-9a-f-]{36}$' }, WRITE_PAYLOAD),
      event(CRON_FINISHED, 'A scheduled gbrain cron you are watching reported its run as ok or failed. The payload names the cron and the status; read its output where the cron writes it.',
        'name', { type: 'string', pattern: '^[a-z0-9._-]{1,64}$' }, CRON_PAYLOAD),
    ],
  };
}

/** A short hash of the manifest this build publishes; `enable` stores it so status and doctor can tell a stale one. */
export function wakeshiftManifestHash(): string {
  return createHash('sha256').update(JSON.stringify(wakeshiftManifest())).digest('hex').slice(0, 16);
}

/** A cron name as gbrain stores it: lowercased, any run of other characters folded to '-', at most 64 characters; null when nothing is left. */
export function cronName(raw: unknown): string | null {
  if (typeof raw !== 'string') return null;
  const name = raw.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64);
  return name || null;
}

export interface JobSnapshot {
  id: number;
  name: string | null;
  status: string | null;
  started_at: Date | string | null;
  finished_at: Date | string | null;
  /** finished_at in microseconds since the epoch (terminal-events.ts ordering), null when the row is gone. */
  finished_us: string | null;
}

const PHRASE: Record<string, string> = {
  completed: 'finished ok', failed: 'failed', dead: 'is dead (out of attempts)', cancelled: 'was cancelled', gone: 'finished; its details are gone',
};

function iso(v: Date | string | null): string | null {
  if (v == null) return null;
  const d = v instanceof Date ? v : new Date(v);
  return Number.isNaN(d.getTime()) ? null : d.toISOString();
}

export function formatDuration(ms: number): string {
  const s = Math.round(ms / 1000);
  if (s < 60) return `${s}s`;
  const m = Math.floor(s / 60);
  if (m < 60) return `${m}m${String(s % 60).padStart(2, '0')}s`;
  return `${Math.floor(m / 60)}h${String(m % 60).padStart(2, '0')}m`;
}

/** The job's terminal marker `<finished_us>:<status>` (`gone` when the row was removed). */
export function jobMarker(job: JobSnapshot | null): string {
  return job?.status ? `${job.finished_us ?? '0'}:${job.status}` : 'gone';
}

/**
 * Emit id: `<event>:<target>:<marker>:<watch row id>:<namespace>`, so two watchers and a re-run job never collide,
 * and neither do two brains (or a re-initialized one) on one Wakeshift key, whose job and row ids restart at 1.
 */
export function wakeEmitId(event: string, target: string, marker: string, rowId: number | string, namespace: string): string {
  return `${event}:${target}:${marker}:${rowId}:${namespace}`;
}

/** Payload and the line the agent reads first, for a watched job (or its removed row). */
export function jobWake(jobId: number, job: JobSnapshot | null): { payload: Record<string, unknown>; text: string } {
  const status = job?.status ?? 'gone';
  const started = iso(job?.started_at ?? null);
  const finished = iso(job?.finished_at ?? null);
  const duration = started && finished ? Math.max(0, Date.parse(finished) - Date.parse(started)) : null;
  const next = status === 'gone' ? `list_jobs (job ${jobId} was removed after it finished)` : `get_job ${jobId}`;
  const kind = job?.name ? ` (${job.name.slice(0, 100)})` : '';
  const took = duration != null ? ` in ${formatDuration(duration)}` : '';
  return {
    payload: { job: jobId, ...(job?.name ? { name: job.name.slice(0, 100) } : {}), status, started_at: started, finished_at: finished, duration_ms: duration, next },
    text: status === 'gone'
      ? `gbrain: job ${jobId} ${PHRASE.gone}. Call list_jobs to see recent jobs.`
      : `gbrain: job ${jobId}${kind} ${PHRASE[status] ?? status}${took}. Call get_job ${jobId} for the result.`,
  };
}

export interface WriteSnapshot {
  state: string | null;
  operation: string | null;
  source_id: string | null;
  created_at: Date | string | null;
  settled_at: Date | string | null;
  /** settled_at in microseconds since the epoch, null when the request row is gone. */
  settled_us: string | null;
}

/** A write request's settled marker `<state>:<settled_us>` (`gone` when the receipt row was removed). */
export function writeMarker(req: WriteSnapshot | null): string {
  return req?.state ? `${req.state}:${req.settled_us ?? '0'}` : 'gone';
}

const WRITE_PHRASE: Record<string, string> = { committed: 'committed', failed: 'failed', conflict: 'ended in a conflict', cancelled: 'was cancelled' };

/** Payload and line for a watched write request: ids, state, operation, source and times, never the slug, title or text. */
export function writeWake(requestId: string, req: WriteSnapshot | null): { payload: Record<string, unknown>; text: string } {
  const state = req?.state ?? 'gone';
  const next = state === 'gone' ? `list_write_requests (request ${requestId} is no longer kept)` : `get_write_request ${requestId}`;
  const op = req?.operation ? ` (${req.operation.slice(0, 100)})` : '';
  return {
    payload: {
      request_id: requestId, state, operation: req?.operation?.slice(0, 100) ?? null, source_id: req?.source_id?.slice(0, 100) ?? null,
      accepted_at: iso(req?.created_at ?? null), settled_at: iso(req?.settled_at ?? null), next,
    },
    text: state === 'gone'
      ? `gbrain: write request ${requestId} settled; its receipt is no longer kept. Call list_write_requests to see recent ones.`
      : `gbrain: write request ${requestId}${op} ${WRITE_PHRASE[state] ?? state}. Call get_write_request ${requestId} for the receipt.`,
  };
}

export interface CronRun { id: number | string; status: string; finished_at: Date | string | null }

/** A cron run's marker `<run id>:<status>`. */
export function cronMarker(run: CronRun): string {
  return `${run.id}:${run.status}`;
}

/** Payload and line for a watched cron's run. No report slug: the agent reads the output where the cron writes it. */
export function cronWake(name: string, run: CronRun): { payload: Record<string, unknown>; text: string } {
  const next = `watch_cron ${name} to hear about its next run`;
  return {
    payload: { name, status: run.status, finished_at: iso(run.finished_at), next },
    text: `gbrain: cron ${name} finished ${run.status === 'ok' ? 'ok' : 'with a failure'}${iso(run.finished_at) ? ` at ${iso(run.finished_at)!.slice(0, 16).replace('T', ' ')} UTC` : ''}. Read its output where it writes it; call watch_cron ${name} to hear about the next run.`,
  };
}