Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.7 KB
Raw Blame
/**
 * v0.29 — Tool descriptions, extracted to a constants module so that:
 *   1. The exact LLM-facing strings are pinnable in tests
 *      (`test/operations-descriptions.test.ts`).
 *   2. Routing changes ship as data, not buried-in-handler edits.
 *   3. The `salience-llm-routing.test.ts` Tier-2 eval has a stable surface
 *      to load tool definitions from.
 *
 * Description style:
 *   - Lead with what the tool does in one short sentence.
 *   - Include explicit triggers ("Use this when the user asks ...") that
 *     the LLM tool-selection prompt can match.
 *   - For redirect hints (query/search → salience), be blunt:
 *     "Do NOT run a semantic search for these."
 */

// ──────────────────────────────────────────────────────────────────────────────
// New v0.29 ops
// ──────────────────────────────────────────────────────────────────────────────

export const GET_RECENT_SALIENCE_DESCRIPTION =
  "Recently touched pages ranked by salience. Use this when the user asks what's been going on, what's notable, anything crazy happening. Do NOT run a semantic search for these.";

export const FIND_ANOMALIES_DESCRIPTION =
  "Anomalies in recent page activity, grouped by cohort (tag or type) against a baseline. Use for what stood out, what's unusual or changed. Cohort kinds: tag, type.";

export const FIND_EXPERTS_DESCRIPTION =
  "Answers 'who in my brain knows about <topic>'. Returns ranked person/company " +
  "pages by expertise depth (sub-linear match score), relationship recency " +
  "(exp decay with 6-month half-life), and salience. Use this for questions " +
  "like 'who should I talk to about X', 'who knows about Y', 'find me someone " +
  "who's worked on Z', or any expertise-routing intent. Filters at SQL to " +
  "person + company pages — does NOT return notes or articles. Pair with " +
  "--explain (CLI) to surface the per-result factor breakdown.";

export const GET_RECENT_TRANSCRIPTS_DESCRIPTION =
  "Returns one-line summaries of recent raw conversation transcripts (NOT polished " +
  "reflections). Use this FIRST for questions about 'what's going on with me', " +
  "'what have I been thinking about', or anything personal/emotional. Raw " +
  "transcripts are the canonical source for the user's own state — polished pages " +
  "summarize and flatten. Local-only: rejects remote (MCP/HTTP) callers with a " +
  "clear permission_denied; call via the gbrain CLI.";

// ──────────────────────────────────────────────────────────────────────────────
// Redirect hints appended to existing op descriptions
// ──────────────────────────────────────────────────────────────────────────────

export const LIST_PAGES_DESCRIPTION =
  "List pages by type, slug_prefix, frontmatter where; what did I touch this week: sort=updated_desc. Default 50; truncated: continue with updated_after + updated_after_slug from the last row.";

export const QUERY_DESCRIPTION =
  "Hybrid search for concept/landscape questions and people/companies/projects by topic; adds fact rows. expand: one LLM call (expansion recovers synonyms; rarely helps). Still top-K; return_unit: sections or conversations. Lists: list_pages. Exact tokens: `search` is cheaper. Personal: get_recent_salience, find_anomalies; transcripts: `gbrain transcripts recent`. Do NOT assume 'crazy' means impressive (often difficult or emotionally charged). Needs an embedding key (else keyword-only); expansion needs a chat key. Fact rows: use follow_up. fields: \"full\" adds diagnostics.";

export const SEARCH_DESCRIPTION =
  "Cheap hybrid search, no LLM expansion, top 20: exact tokens, names, field values. NOT proof of coverage; match: \"keyword\" pages every keyword match and takes OR across quoted names or codes (\"A\" OR \"B\" OR …): one call lists every page matching any. Name lists: entity names. Concepts/landscape or people/companies/projects by topic: `query`; lists: list_pages; personal: get_recent_salience. return_unit: sections or conversations. fields: \"full\" adds diagnostics.";

/** `search`'s `match` param (Cat 40 Hard F2). */
export const SEARCH_MATCH_DESCRIPTION = 'keyword: every match, paged.';

// ──────────────────────────────────────────────────────────────────────────────
// v0.32.6 — contradiction probe MCP surface (M3)
// ──────────────────────────────────────────────────────────────────────────────

export const FIND_CONTRADICTIONS_DESCRIPTION =
  "Return suspected-contradiction findings from the most recent " +
  "`gbrain eval suspected-contradictions` probe run, optionally filtered by slug " +
  "and/or severity. Use this when the user asks 'what's inconsistent in my " +
  "brain', 'show me contradictions about Acme', 'high-severity issues only', or " +
  "wants to act on the probe's findings without re-running it. Returns " +
  "{contradictions: [{a, b, severity, axis, confidence, resolution_command}]}. " +
  "Remote, source-scoped or min_trust callers get only findings whose two sides they can read now " +
  "(each side re-read live, with source_id, trust_tier and origin) and total_visible instead of the run total. " +
  "Reads the stored run without triggering a new probe; users run " +
  "`gbrain eval suspected-contradictions` for that.";

export const FIND_TRAJECTORY_DESCRIPTION =
  "Return the chronological claim trajectory for an entity (typed " +
  "metric values over time, plus auto-detected regressions and narrative drift). " +
  "Use this when the user asks 'how has Acme's MRR trended', 'show me what " +
  "alice-example said about runway over time', 'is this founder consistent', " +
  "'find regressions for fund-a's portfolio', or wants a time-series view of an " +
  "entity's structured claims. Returns " +
  "`{points: [{fact_id, valid_from, metric, value, unit, period, text, source_session, source_markdown_slug}], " +
  "regressions: [{metric, from_value, from_date, to_value, to_date, delta_pct}], " +
  "drift_score: number|null, schema_version: 1}`. Drift score 0 = stable narrative, " +
  "1 = every consecutive claim is unrelated; null when fewer than 3 typed points " +
  "exist. Visibility-filtered for remote callers (world-only); source-scoped by " +
  "the caller's OAuth source binding. Pair with `gbrain founder scorecard <slug>` " +
  "for an aggregated rollup of the same data.";

// ──────────────────────────────────────────────────────────────────────────────
// v0.33.3 Cathedral III foundation — code-intelligence ops (MCP-exposed).
// Pre-v0.33.3 the callers/callees/def/refs commands were CLI-only — agents
// reached for grep because the MCP surface didn't expose them. These
// descriptions are resolver-grade so the LLM tool-selection prompt routes
// plan-mode questions straight to the right op.
//
// Style notes per the v0.34 eng review D10 finding: every description carries
// an inline example response so agents don't burn first-call context discovering
// shape. Pin via test/operations-descriptions.test.ts.
// ──────────────────────────────────────────────────────────────────────────────

export const CODE_CALLERS_DESCRIPTION =
  "BEFORE editing any function, run code_callers with the symbol name to find " +
  "every caller (the people who'd be affected by your change). Returns direct " +
  "callers from the tree-sitter call graph. Use during plan-mode to size " +
  "the change. Defaults to source-scoped; for multi-source brains pass source_id " +
  "or all_sources=true. `resolved:false` marks a call matched by name only: the resolver links calls within one " +
  "file, so a cross-file call stays unresolved and may name a different symbol with the same name. " +
  "Returns: `{symbol, count, callers: [{from_symbol_qualified, to_symbol_qualified, edge_type, resolved}]}`. " +
  "Example: `{symbol:'parseMarkdown', count:4, callers:[{from_symbol_qualified:'callerInA', " +
  "to_symbol_qualified:'parseMarkdown', edge_type:'calls', resolved:true}]}`.";

export const CODE_CALLEES_DESCRIPTION =
  "When tracing how a function flows to its dependencies (DB calls, HTTP calls, " +
  "file I/O), run code_callees from the entry point. Forward view of the call " +
  "graph: what does this symbol call? Use this when debugging unexpected behavior " +
  "or when planning to extract / inline a function. Same shape as code_callers " +
  "but the field is `callees` and the edge direction is reversed.";

export const CODE_DEF_DESCRIPTION =
  "Where is this symbol defined? Returns one row per definition site (function, " +
  "class, type, interface, enum, struct, trait, module, contract). Use this BEFORE " +
  "reaching for grep when you want to read a definition. Single-result is the common " +
  "case; multiple results indicate same-name symbols across files (which is information " +
  "in itself). " +
  "Returns: `{symbol, count, defs: [{slug, file, language, symbol_type, start_line, end_line, snippet}]}`. " +
  "Filter by --lang to scope a polyglot brain (e.g., lang='typescript').";

export const CODE_REFS_DESCRIPTION =
  "Find every reference to a symbol across the codebase (every file, every line). " +
  "Differs from code_callers in two ways: (1) catches references in comments, " +
  "strings, imports, type annotations — not just call sites; (2) returns line " +
  "numbers, not symbol-qualified edges. Use this when planning a rename or " +
  "deprecation where you need to touch every literal mention. " +
  "Returns: `{symbol, count, refs: [{slug, file, language, line, context}]}`.";

// ──────────────────────────────────────────────────────────────────────────────
// PR1 — skill catalog over MCP (list_skills / get_skill). The agent repo's
// fat-markdown skills, published so a thin MCP client (Codex desktop, Claude
// Code, Perplexity) can discover and FOLLOW them. Skills are prose instruction
// sets, not executable code — "using" one = fetching its prose and then calling
// the gbrain MCP tools the same server already exposes. The instructional
// envelope below is the load-bearing UX: it tells the pulling agent what these
// are and the use protocol. Pinned by test/operations-descriptions.test.ts.
// ──────────────────────────────────────────────────────────────────────────────

export const LIST_SKILLS_DESCRIPTION =
  "Skills: prose instruction sets (NOT executable code) for tasks with this server's tools, with triggers, usable_tools and unavailable_tools. Use one via get_skill.";

export const GET_SKILL_DESCRIPTION =
  "Fetch a skill's prose and follow it: when it says search or store, call the same-named MCP tool here. There is nothing to execute. unavailable_tools won't work for you.";

/**
 * The load-bearing `instructions` envelope for list_skills. Pinned so the
 * agent-facing protocol can't silently drift. `how_to_use` is the ordered
 * protocol a thin client follows.
 */
export const SKILL_CATALOG_INSTRUCTIONS = {
  summary:
    "These are 'skills': named prose instruction sets, not executable tools. " +
    "There is no skill to 'run' — a skill tells YOU how to accomplish a task " +
    "using the MCP tools this same server already exposes.",
  how_to_use: [
    "Pick a skill from this list whose triggers match the user's intent.",
    "Call get_skill with its name to fetch the full prose (the `body`).",
    "Follow that prose as your plan for the task.",
    "When the prose says to search, store, link, or look something up, call the " +
      "correspondingly-named MCP tool on THIS server (e.g. search, query, put_page).",
    "Only call tools in this skill's `usable_tools`; tools in `unavailable_tools` " +
      "are not callable by you on this server.",
    "For host-repository skills, declared `tools` narrow the usable tools. Valid " +
      "frontmatter without `tools` inherits your available brain tools; `tools: []` permits none. " +
      "Canonical shared skills follow the same rule; their other requirements gate `usable`.",
  ],
} as const;

/**
 * Per-skill `client_guidance` for get_skill. Same protocol, scoped to one skill.
 */
export const SKILL_CLIENT_GUIDANCE = {
  nature:
    "This is a fat-markdown instruction set, not code to execute. The `body` is " +
    "your operating procedure; carry it out using this server's MCP tools.",
  protocol: [
    "Read `body` as your operating instructions for this task.",
    "When the prose names a brain operation (search, store, link, look up), call " +
      "the MCP tool of that name on THIS server.",
    "Do not invent tools — only the tools in `usable_tools` are callable by you.",
    "For host-repository skills, declared `tools` narrow this list. Valid frontmatter " +
      "without `tools` inherits your available brain tools; `tools: []` permits none. " +
      "Canonical shared skills follow the same rule; their other requirements gate `usable`.",
    "If `mutating` is true, this skill writes to the brain; confirm before doing so " +
      "if the user hasn't clearly asked for a write.",
  ],
} as const;

/**
 * CLI→MCP gap-closure wave — the capture op (D2A). Pinned here because it
 * rewrites the routing guidance three docs used to carry as the
 * "unknown tool: capture → use put_page" FAQ: agents must learn the split
 * (capture = quick notes with auto-slug + dedupe; put_page = full control)
 * from this description alone. Phrase-pinned by
 * test/operations-descriptions.test.ts.
 */
export const CAPTURE_DESCRIPTION =
  "Quick note (\"just remember this\"): slugged under inbox/ by date + content hash, so recapturing is idempotent. put_page controls slug or type; remember is for facts about entities.";