Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.2 KB
Raw Blame
/**
 * GBRA-156: the next command `gbrain sources add` prints when a new
 * non-federated source leaves the no-grant floor holding no page.
 *
 * A remote token or agent connection with no source grant reads the default
 * source plus the federated ones. When none of those holds a page, such a
 * connection is refused (`sources_not_readable`) until a source is federated
 * or the connection is granted sources, so the add says which command makes
 * the new source readable. The stored federation default is unchanged.
 */
import type { BrainEngine } from '../core/engine.ts';
import type { Notice, RenderedNotice } from '../core/agent-output.ts';
import { newSourceJoinsDefaultSearch } from '../core/source-default-search.ts';
import { localFederatedSourceIds } from '../core/source-resolver.ts';
import { privatePagesFilterFragment, resolveExcludePrivatePages } from '../core/search/private-visibility.ts';
import { quarantineFilterFragment } from '../core/quarantine.ts';

export interface SourcesAddNext {
  command: string;
  argv: string[];
  why: string;
}

/** The federate step for `id` when the no-grant floor holds no live, unquarantined page a remote read may show, else null. */
export async function noGrantFloorNext(engine: BrainEngine, id: string): Promise<SourcesAddNext | null> {
  const floor = (await localFederatedSourceIds(engine, 'default', 'seed_default')) ?? ['default'];
  const visible = ` AND ${quarantineFilterFragment('p')}`
    + (await resolveExcludePrivatePages(engine, true) ? ` AND ${privatePagesFilterFragment('p')}` : '');
  const [row] = await engine.executeRaw<{ holds: boolean }>(
    `SELECT EXISTS (SELECT 1 FROM pages p WHERE p.source_id = ANY($1::text[]) AND p.deleted_at IS NULL${visible}) AS holds`, [floor]);
  if (row?.holds) return null;
  const argv = ['gbrain', 'sources', 'federate', id];
  return {
    command: argv.join(' '),
    argv,
    why: `Connections with no source grant read only the default source and federated sources, and none of them holds a page every reader of its source can read, so their empty reads are refused until "${id}" is federated or they are granted sources.`,
  };
}

/** The notice for a source left out of default search; shared says the brain's shape kept it out. Federating is the user's call when shared or when `ask` (a source that predates this add). */
export function notInDefaultSearchNotice(id: string, shared: boolean, ask = shared): Notice {
  return {
    code: 'source_not_in_default_search',
    kind: 'info',
    why: `The source "${id}" is not federated, so it is not in default search: a search, query or recall that names no source leaves its pages out, and a remote token or agent connection with no source grant cannot read them.`
      + (shared ? ' This brain serves several people or is not marked personal, so a new source stays out until someone chooses to add it.' : '')
      + ` To share it with every connection that reads default search, run \`gbrain sources federate ${id}\`; to share it with one token, \`gbrain auth rescope --token <name> --sources ${id}\`. A source meant to stay private needs nothing.`,
    fix: {
      argv: ['gbrain', 'sources', 'federate', id],
      consent: [],
      actor: 'agent',
      ...(ask ? { ask_user: true as const } : {}),
      requires_exclusive: false,
      why: 'Adds the source to default search and to what connections with no source grant can read.',
      verify: { argv: ['gbrain', 'sources', 'list', '--json'] },
    },
    ...(ask ? { user_message: `Should the source "${id}" be shared with every connection that reads this brain's default search? If yes, the command shown adds it. If it is meant for one person or a few connections, leave it as it is.` } : {}),
  };
}

/** After `gbrain sync --source <id>`: the same notice when that source holds pages and its federated setting is unset. */
export async function syncOutOfSearchNotice(engine: BrainEngine, args: string[]): Promise<Notice | null> {
  if (args[0] === 'status' || args[0] === 'unblock' || args.includes('--dry-run')) return null;
  const id = args.find((_, i) => args[i - 1] === '--source');
  if (!id || id === 'default') return null;
  try {
    const [row] = await engine.executeRaw<{ f: unknown; remote: unknown; pages: number }>(
      `SELECT config->'federated' AS f, config->'added_by_remote_caller' AS remote, (SELECT count(*)::int FROM pages WHERE source_id = $1 AND deleted_at IS NULL) AS pages FROM sources WHERE id = $1`, [id]);
    if (!row || row.f != null || row.remote === true || !Number(row.pages)) return null;
    return notInDefaultSearchNotice(id, !(await newSourceJoinsDefaultSearch(engine)), true);
  } catch {
    return null;
  }
}

/** Writes the sync notice on stderr when it applies. */
export async function noteSyncOutOfSearch(engine: BrainEngine, args: string[]): Promise<void> {
  const notice = await syncOutOfSearchNotice(engine, args);
  if (notice) (await import('../cli/cli-error.ts')).writeCliNotice(notice);
}

/**
 * GST-2732: what a finished add means, for both CLI add paths. `chosen` is the --federated / --no-federated choice
 * (null when none was made); `path` is the local folder of a plain --path add, else null. Prints on `say`, writes the
 * notice on stderr unless json, and returns the rendered notices for the JSON document.
 */
export async function reportAddOutcome(input: { id: string; chosen: boolean | null | undefined; federated: boolean; path: string | null; json: boolean; say: (line: string) => void }): Promise<RenderedNotice[] | undefined> {
  const { existsSync } = await import('node:fs');
  if (input.path && existsSync(input.path) && !(await import('../core/git-remote.ts')).inGitCheckout(input.path)) {
    input.say('  plain folder (not a git repository): sync imports its files without Git, so git history is off and a file removed from it keeps its page');
  }
  if (input.chosen != null) return undefined;
  if (input.federated) {
    input.say(`  this brain serves one person, so a new source joins default search; \`gbrain sources unfederate ${input.id}\` takes it out`);
    return undefined;
  }
  const notice = notInDefaultSearchNotice(input.id, true);
  if (!input.json) (await import('../cli/cli-error.ts')).writeCliNotice(notice);
  const { cliRenderContext, renderNotice } = await import('../core/agent-output.ts');
  return [renderNotice(notice, cliRenderContext())];
}