Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
20.8 KB
Raw Blame
/**
 * gbrain waiting / gbrain loops — the open-loop engine's human CLI.
 *
 *   gbrain waiting [--top N] [--json] [--stale-ok]
 *     The killer output: ranked people waiting on you, what you promised,
 *     evidence quotes + Gmail deep links, entity-card context.
 *     REFUSES (with the exact fix) when the google sources haven't synced
 *     within 24h — stale-but-confident output on a trust-critical surface is
 *     worse than none (outside-voice F2). --stale-ok bypasses.
 *
 *   gbrain loops list [--status s] [--type t] [--json]
 *   gbrain loops show <id> [--json]
 *   gbrain loops done <id> / drop <id>
 *   gbrain loops drop sender <email> [--source <id>] [--note <text>] [--dry-run]
 *   gbrain loops mute <sender|thread> <value> [--source <id>] [--dry-run]
 *   gbrain loops unmute <sender|thread> <value> [--source <id>] [--dry-run]
 *
 * All paths dispatch through the trusted-local op layer (handleToolCall,
 * remote:false) so CLI and MCP share one behavior. Reads default to the
 * `__all__` brain span (loops live in google sources, not 'default' — an
 * unqualified dispatch would silently scope to 'default' and answer "You are
 * clean" while people wait); `--source <id>` narrows explicitly.
 */

import type { BrainEngine } from '../core/engine.ts';
import { handleToolCall } from '../mcp/server.ts';
import { setCliExitVerdict } from '../core/cli-force-exit.ts';
import { ALL_SOURCES } from '../core/source-id.ts';
import { exitCliError, usageError, writeCliError } from '../cli/cli-error.ts';
import { opError } from '../core/ops/contract.ts';
import { LOOPS_SUBCOMMANDS, ROUTERS, subcommandHelpRequested } from '../cli/subcommands.ts';

export { LOOPS_SUBCOMMANDS as SUBCOMMANDS } from '../cli/subcommands.ts';

export function printUsage(): void {
  process.stdout.write(
    [
      'gbrain loops — inspect and manage open loops',
      '  list  [--status open|done|dropped|stale] [--type <loop_type>] [--source <id>] [--json]',
      '  show  <id> [--json]',
      '  done  <id> [--note <text>]   mark handled',
      '  drop  <id> [--note <text>]   not going to do it',
      '  drop  sender <email> [--source <id>] [--note <text>] [--dry-run]',
      '        close every open reply-owed loop from one sender (preview with --dry-run; cannot be undone)',
      '  mute  sender <email> | thread <thread-id>   [--source <id>] [--dry-run]',
      '        stop new loops and close its open reply-owed loops',
      '  unmute sender <email> | thread <thread-id>  [--source <id>] [--dry-run]',
      '        undo a mute; loops it closed are re-checked on the next sync',
      '',
      'The ranked digest lives at: gbrain waiting',
    ].join('\n') + '\n',
  );
}

function sourceFlag(args: string[]): string | undefined {
  const i = args.indexOf('--source');
  return i !== -1 ? args[i + 1] : undefined;
}

/** Non-archived sources whose config says kind=google (mute's default scope). */
async function googleSourceIds(engine: BrainEngine): Promise<string[]> {
  const rows = await engine.executeRaw<{ id: string; config: unknown }>(
    `SELECT id, config FROM sources WHERE archived IS NOT TRUE`,
    [],
  );
  return rows
    .filter((r) => {
      const c =
        typeof r.config === 'string'
          ? (JSON.parse(r.config) as Record<string, unknown>)
          : ((r.config ?? {}) as Record<string, unknown>);
      return c.kind === 'google';
    })
    .map((r) => r.id);
}

interface WaitingResult {
  groups: Array<{
    counterparty: string;
    loop_count: number;
    nearest_due_at: string | null;
    loops: Array<{
      id: number;
      loop_type: string;
      summary: string;
      due_at: string | null;
      quote?: string;
      deep_link?: string;
      page_slug: string | null;
    }>;
    context?: { summary?: string; last_touched?: { last_timeline_date?: string | null } };
  }>;
  /** #5871: loops that name no counterparty, listed apart from the people; null when none. */
  no_counterparty?: { loop_count: number } | null;
  /** #5012: open reply-owed loops the automated-mail rule would not have opened; null when none. */
  withheld_noise?: { loop_count: number; sender_count: number; senders: Array<{ email: string; open_loops: number; preview_command: string }> } | null;
  count: number;
  stale: boolean;
  sources: Array<{ id: string; last_sync_at: string | null; stale: boolean }>;
  /** Fix wave 4: `partial` when a held Gmail thread falls inside the window (listed in `held`). */
  completeness?: 'complete' | 'partial';
  held?: Array<{ source_id: string; key: string; sender: string | null; subject?: string | null; retry_command: string }>;
  text?: string;
}

export async function runWaiting(engine: BrainEngine, args: string[]): Promise<void> {
  if (args.includes('--help') || args.includes('-h')) {
    process.stdout.write(
      [
        'gbrain waiting — who is waiting on you, what you promised, the context to respond',
        '  --top N        max counterparties (default 3)',
        '  --source <id>  scope to one source (default: every source in the brain)',
        '  --json         agent envelope (groups, staleness, completeness, held items, sources)',
        '  --stale-ok     show possibly-outdated loops even when google sources have not synced in 24h',
        '  --as-of <iso>  rank and age loops as of this time (default: now), to reproduce an order',
        '',
        'Manage loops: gbrain loops --help · Setup: gbrain google setup · Docs: docs/guides/open-loops.md',
      ].join('\n') + '\n',
    );
    return;
  }
  const json = args.includes('--json');
  const staleOk = args.includes('--stale-ok');
  const topIdx = args.indexOf('--top');
  const top = topIdx !== -1 ? Number(args[topIdx + 1]) || 3 : 3;
  const asOfIdx = args.indexOf('--as-of');

  const result = (await handleToolCall(
    engine,
    'open_loops',
    { group_by: 'counterparty', limit: top, include_context: true, ...(asOfIdx !== -1 ? { as_of: args[asOfIdx + 1] } : {}) },
    { sourceId: sourceFlag(args) ?? ALL_SOURCES },
  )) as WaitingResult;

  if (result.stale && !staleOk) {
    const staleSrc = result.sources.filter((s) => s.stale);
    const lines = [
      'Refusing to answer from stale data — every google source is out of date:',
      ...staleSrc.map(
        (s) => `  ${s.id}: last successful sync ${s.last_sync_at ?? 'never'}`,
      ),
      '',
      'Fix: run a sync first, then retry:',
      ...staleSrc.map((s) => `  gbrain sync --source ${s.id}`),
      '',
      '(or pass --stale-ok to see the possibly-outdated loops anyway)',
    ];
    if (json) {
      process.stdout.write(
        JSON.stringify({ ok: false, status: 'stale', sources: result.sources, next_action: { command: staleSrc[0] ? `gbrain sync --source ${staleSrc[0].id}` : 'gbrain sync --all' } }, null, 2) + '\n',
      );
    } else {
      process.stderr.write(lines.join('\n') + '\n');
    }
    setCliExitVerdict(1);
    return;
  }

  if (json) {
    process.stdout.write(JSON.stringify({ ok: true, status: 'ok', ...result }, null, 2) + '\n');
    return;
  }
  process.stdout.write((result.text ?? 'No open loops.') + '\n');
  const noise = result.withheld_noise;
  if (noise) {
    process.stdout.write(`\n${noise.loop_count} open reply-owed loop(s) come from ${noise.sender_count} sender(s) whose mail is automated; `
      + `the detector would not open them now. Preview closing them, sender by sender:\n`
      + noise.senders.slice(0, 10).map((x) => `  ${x.preview_command}   (${x.open_loops})`).join('\n') + '\n'
      + (noise.sender_count > 10 ? `  … and ${noise.sender_count - 10} more sender(s); every sender: gbrain waiting --json\n` : ''));
  }
  if (result.groups.length > 0 || result.no_counterparty) {
    process.stdout.write(
      `\n(close: gbrain loops done <id> · mute a sender: gbrain loops mute sender <email> · details: gbrain loops list)\n`,
    );
  }
}

/**
 * `loops show <id>`: asks open_loops for that one id rather than scanning a
 * listed page, so the loop is found at any status and any recency rank.
 * `--status` / `--type` still narrow, and the source span is the same one
 * `loops list` reads.
 */
async function showLoop(
  engine: BrainEngine,
  rest: string[],
  narrowing: Record<string, unknown>,
  readScope: { sourceId: string },
  json: boolean,
): Promise<void> {
  const token = rest.find((a) => /^\d+$/.test(a));
  const loopId = token === undefined ? NaN : Number(token);
  if (!Number.isSafeInteger(loopId) || loopId < 1) {
    exitCliError(usageError('gbrain loops show needs a loop id of 1 or more.',
      'Usage: gbrain loops show <id> [--json]. Example: gbrain loops show 42 (`gbrain loops list` prints ids).'), 'loops', { json });
  }
  const { loops } = (await handleToolCall(
    engine,
    'open_loops',
    { group_by: 'none', id: loopId, ...narrowing },
    readScope,
  )) as { loops: Array<Record<string, unknown>> };
  const loop = loops[0];
  if (loop === undefined) {
    setCliExitVerdict(writeCliError(opError('not_found', `No loop ${loopId} in the sources this command reads.`,
      'Run `gbrain loops list` to see loop ids.', {
        why: 'A loop in a source this command does not read, or one excluded by --status or --type, is reported the same way as an id that does not exist.',
        fix: { argv: ['gbrain', 'loops', 'list'], consent: [], actor: 'agent', why: 'Prints the loops this command can read, with their ids.', requires_exclusive: false },
      }), 'loops', { json }));
    return;
  }
  if (json) {
    process.stdout.write(JSON.stringify({ ok: true, status: 'ok', loop }, null, 2) + '\n');
    return;
  }
  const due = loop.due_at ? `  due ${String(loop.due_at).slice(0, 10)}` : '';
  process.stdout.write(`#${String(loop.id)} [${String(loop.loop_type)}] ${String(loop.status)}${due}\n${String(loop.summary)}\n`);
  const quote = (loop as { quote?: string }).quote;
  if (quote) process.stdout.write(`> "${quote}"\n`);
  const link = (loop as { deep_link?: string }).deep_link;
  if (link) process.stdout.write(`${link}\n`);
}

function idList(ids: number[]): string {
  if (ids.length === 0) return '';
  return `: ${ids.slice(0, 20).join(', ')}${ids.length > 20 ? `, +${ids.length - 20} more` : ''}`;
}

/**
 * #5012: `gbrain loops drop sender <email>` closes every open reply-owed
 * (unanswered_inbound) loop from one sender as `dropped`, one `loops_close`
 * per loop, so each id reports its own outcome. `--dry-run` is the consent
 * step: it lists the ids and count and changes nothing. A drop is final: no
 * command reopens a dropped loop (`mute` is the reversible path).
 */
async function dropSender(engine: BrainEngine, rest: string[], json: boolean): Promise<void> {
  const email = rest[1]?.trim().toLowerCase();
  if (!email || email.startsWith('-') || !email.includes('@')) {
    exitCliError(usageError('gbrain loops drop sender needs an email address.',
      'Usage: gbrain loops drop sender <email> [--source <id>] [--note <text>] [--dry-run]. Preview first with --dry-run.'), 'loops', { json });
  }
  const source = sourceFlag(rest);
  const noteIdx = rest.indexOf('--note');
  const note = noteIdx !== -1 ? rest[noteIdx + 1] : undefined;
  const { listSenderInboundLoops } = await import('../core/loops/loops-store.ts');
  const loops = await listSenderInboundLoops(engine, email!, source ? [source] : null);
  const ids = loops.map((l) => l.id);
  const apply = `gbrain loops drop sender ${email}${source ? ` --source ${source}` : ''}${note !== undefined ? ` --note ${JSON.stringify(note)}` : ''}`;
  if (rest.includes('--dry-run')) {
    if (json) {
      process.stdout.write(JSON.stringify({ ok: true, status: 'dry_run', sender: email, source_id: source ?? null, would_close: ids, count: ids.length,
        ...(ids.length > 0 ? { apply_command: apply } : {}) }, null, 2) + '\n');
    } else if (ids.length === 0) {
      process.stdout.write(`No open reply-owed loops from ${email}. Nothing to drop.\n`);
    } else {
      process.stdout.write(`Dry run: ${ids.length} open reply-owed loop(s) from ${email} would be dropped${idList(ids)}. Nothing changed.\n`
        + `To drop them (cannot be undone): ${apply}\n`);
    }
    return;
  }
  const closed: number[] = [];
  const failed: Array<{ id: number; reason: string }> = [];
  for (const loop of loops) {
    try {
      const result = (await handleToolCall(engine, 'loops_close', { id: loop.id, status: 'dropped', source_id: loop.source_id,
        note: note ?? `drop sender ${email}` })) as { closed: boolean; reason?: string };
      if (result.closed) closed.push(loop.id);
      else failed.push({ id: loop.id, reason: result.reason ?? 'not_closed' });
    } catch (e) {
      failed.push({ id: loop.id, reason: e instanceof Error ? e.message : String(e) });
    }
  }
  if (json) {
    process.stdout.write(JSON.stringify({ ok: failed.length === 0, status: failed.length === 0 ? 'dropped' : 'partial', sender: email,
      source_id: source ?? null, closed, failed, count: closed.length }, null, 2) + '\n');
  } else {
    process.stdout.write(`Dropped ${closed.length} open reply-owed loop(s) from ${email}${idList(closed)}.\n`
      + (failed.length > 0 ? `${failed.length} could not be dropped: ${failed.slice(0, 10).map((f) => `${f.id} (${f.reason})`).join(', ')}\n` : '')
      + (closed.length > 0 ? `To stop new loops from this sender too: gbrain loops mute sender ${email}${source ? ` --source ${source}` : ''}\n` : ''));
  }
  if (failed.length > 0) setCliExitVerdict(1);
}

export async function runLoops(engine: BrainEngine, args: string[]): Promise<void> {
  const [first, ...rest] = args;
  const sub = first as (typeof LOOPS_SUBCOMMANDS)[number] | undefined;
  const json = rest.includes('--json') || args.includes('--json');

  // cli.ts answers help before dispatch (#6114 router, #6521: `loops show --help` used to exit 2 "needs a loop id").
  if (!sub || subcommandHelpRequested(args, ROUTERS.loops)) {
    printUsage();
    return;
  }

  if (sub === 'list' || sub === 'show') {
    const statusIdx = rest.indexOf('--status');
    const typeIdx = rest.indexOf('--type');
    const narrowing = {
      ...(statusIdx !== -1 ? { status: rest[statusIdx + 1] } : {}),
      ...(typeIdx !== -1 ? { loop_type: rest[typeIdx + 1] } : {}),
    };
    const readScope = { sourceId: sourceFlag(rest) ?? ALL_SOURCES };
    if (sub === 'show') {
      await showLoop(engine, rest, narrowing, readScope, json);
      return;
    }
    const result = (await handleToolCall(
      engine,
      'open_loops',
      { group_by: 'none', limit: 200, ...narrowing },
      readScope,
    )) as { loops: Array<Record<string, unknown>>; count: number; truncated: boolean };
    if (json) {
      process.stdout.write(JSON.stringify({ ok: true, status: 'ok', ...result }, null, 2) + '\n');
      return;
    }
    if (result.loops.length === 0) {
      process.stdout.write('No loops match.\n');
      return;
    }
    for (const l of result.loops) {
      const due = l.due_at ? `  due ${String(l.due_at).slice(0, 10)}` : '';
      process.stdout.write(`#${String(l.id).padEnd(5)} [${String(l.loop_type)}]${due}  ${String(l.summary)}\n`);
    }
    if (result.truncated) process.stdout.write(`Showing the ${result.loops.length} most recently active of ${result.count}${result.count >= 500 ? '+' : ''} matching loops.\n`);
    return;
  }

  if (sub === 'drop' && rest[0] === 'sender') {
    await dropSender(engine, rest, json);
    return;
  }

  if (sub === 'done' || sub === 'drop') {
    const id = Number(rest.find((a) => /^\d+$/.test(a)));
    if (!Number.isFinite(id) || id <= 0) {
      console.error(`Usage: gbrain loops ${sub} <id>`);
      process.exit(2);
    }
    const noteIdx = rest.indexOf('--note');
    const note = noteIdx !== -1 ? rest[noteIdx + 1] : undefined;
    const result = (await handleToolCall(
      engine,
      'loops_close',
      {
        id,
        status: sub === 'done' ? 'done' : 'dropped',
        ...(note !== undefined ? { note } : {}),
      },
      { sourceId: ALL_SOURCES },
    )) as { closed: boolean; reason?: string; status?: string };
    if (json) {
      // Envelope `status` is the outcome; the loop's terminal state rides as
      // `loop_status` (spreading the op result last would clobber the envelope).
      const { status: loopStatus, ...opResult } = result;
      process.stdout.write(
        JSON.stringify(
          {
            ok: result.closed,
            ...opResult,
            status: result.closed ? 'closed' : 'not_closed',
            ...(loopStatus !== undefined ? { loop_status: loopStatus } : {}),
          },
          null,
          2,
        ) + '\n',
      );
    } else {
      process.stdout.write(result.closed ? `Loop ${id} ${sub === 'done' ? 'done' : 'dropped'}.\n` : `Not closed: ${result.reason}\n`);
    }
    if (!result.closed) setCliExitVerdict(1);
    return;
  }

  if (sub === 'mute' || sub === 'unmute') {
    const kind = rest[0];
    const value = rest[1];
    if ((kind !== 'sender' && kind !== 'thread') || !value) {
      console.error(`Usage: gbrain loops ${sub} sender <email> | thread <thread-id> [--source <id>]`);
      process.exit(2);
    }
    // A suppression row is only consulted by the detector inside ITS source —
    // an unqualified mute/unmute must land in the google source, never
    // 'default'. Both directions share this resolution so an unmute can never
    // aim at a different source than the mute it is reversing.
    let sourceId = sourceFlag(rest);
    if (!sourceId) {
      const gs = await googleSourceIds(engine);
      if (gs.length === 1) sourceId = gs[0];
      else {
        console.error(
          gs.length === 0
            ? `No google source found — pass --source <id> to scope the ${sub} (gbrain sources list).`
            : `Multiple google sources — pass --source <id> (one of: ${gs.join(', ')}).`,
        );
        process.exit(2);
      }
    }
    const dryRun = rest.includes('--dry-run');
    if (sub === 'mute') {
      const result = (await handleToolCall(engine, 'loops_mute', {
        kind,
        value,
        source_id: sourceId,
        ...(dryRun ? { dry_run: true } : {}),
      })) as { muted?: boolean; reason?: string; closed?: number[]; would_close?: number[]; undo_command: string };
      if (dryRun) {
        const ids = result.would_close ?? [];
        if (json) process.stdout.write(JSON.stringify({ ok: true, status: 'dry_run', ...result }, null, 2) + '\n');
        else process.stdout.write(`Dry run: muting ${kind} ${value} would close ${ids.length} open reply-owed loop(s)${idList(ids)}. Nothing changed.\n`);
        return;
      }
      if (json) {
        process.stdout.write(JSON.stringify({ ok: result.muted, status: result.muted ? 'muted' : 'not_muted', ...result }, null, 2) + '\n');
      } else if (result.muted) {
        const closed = result.closed ?? [];
        process.stdout.write(`Muted ${kind} ${value}. New loops won't open for it; closed ${closed.length} open reply-owed loop(s)${idList(closed)}.\n`
          + `Undo: ${result.undo_command} (re-checks the closed loops on the next sync)\n`);
      } else {
        process.stdout.write(`Not muted: ${result.reason}\n`);
      }
      if (!result.muted) setCliExitVerdict(1);
      return;
    }
    const result = (await handleToolCall(engine, 'loops_unmute', {
      kind,
      value,
      source_id: sourceId,
      ...(dryRun ? { dry_run: true } : {}),
    })) as { removed?: boolean; reason?: string; requeued?: number[]; would_requeue?: number[]; unverifiable: number[];
      stale_source?: boolean; recheck_command?: string; undo_command: string };
    if (dryRun) {
      const ids = result.would_requeue ?? [];
      if (json) process.stdout.write(JSON.stringify({ ok: true, status: 'dry_run', ...result }, null, 2) + '\n');
      else process.stdout.write(`Dry run: unmuting ${kind} ${value} would queue ${ids.length} closed loop(s) for re-check${idList(ids)}. Nothing changed.\n`);
      return;
    }
    // A repeated unmute is a no-op, NOT a failure: removed:false exits 0 so
    // scripts can call it unconditionally without special-casing.
    if (json) {
      process.stdout.write(JSON.stringify({ ok: true, status: result.removed ? 'unmuted' : 'not_muted', ...result }, null, 2) + '\n');
    } else {
      const requeued = result.requeued ?? [];
      process.stdout.write(
        (result.removed
          ? `Unmuted ${kind} ${value}. New loops can open for it again.\n`
          : `Not muted: ${kind} ${value} had no suppression in ${sourceId}.\n`)
        + (requeued.length > 0 ? `Queued ${requeued.length} loop(s) the mute closed for re-check on the next sync${idList(requeued)}; each reopens only if nothing answered its thread since.\n` : '')
        + (result.unverifiable.length > 0 ? `${result.unverifiable.length} closed loop(s) have no thread to re-check and stay closed${idList(result.unverifiable)}.\n` : '')
        + (result.stale_source ? `This source has not synced in 24h; the re-check runs on its next sync: ${result.recheck_command}\n` : '')
        + (result.removed ? `Undo: ${result.undo_command}\n` : ''),
      );
    }
    return;
  }

  console.error(`Unknown subcommand: ${sub} (try: gbrain loops --help)`);
  process.exit(2);
}