gemini-advisor

1import type { EngineInterface, Register, ToolCallInput, ToolCallResult } from 'claude-code'
2import { adviceText, buildAdviceBody, INPUT_SCHEMA, messageOf, SYSTEM_GUIDANCE, TOOL_DESCRIPTION, TOOL_NAME, usageText, type Answer } from './advice.ts'
3import { changeText, ENABLED_KEY, NO_KEY_ON, parseCommand, RESET_TEXT, statusText } from './command.ts'
4import { CONSUMER, configFrom, DEADLINE_MS, DEFAULT_MODEL, type Config } from './config.ts'
5import { renderTranscript } from './transcript.ts'
6
7/**
8 * The last advice's usage line, for the status; whether the system prompt
9 * carries the note, fixed at a session start or /clear so a change of the
10 * setting does not change the prompt the cache holds; and whether this session
11 * declared the tool.
12 */
13type State = { last?: string; guidance: boolean; declared: boolean }
14
15/** Gemini's answer, the model and the tier it went to, or why there is none. */
16type Asked = { answer: Answer; model: string; tier: 'free' | 'paid' } | { error: string }
17
18function errorText(err: unknown): string {
19  return err instanceof Error ? err.message : String(err)
20}
21
22/** Off until the user turns it on, so a fresh install offers the model no tool that can only fail. */
23async function isEnabled($: EngineInterface): Promise<boolean> {
24  return (await $.store.get(ENABLED_KEY)) === true
25}
26
27async function declareTool($: EngineInterface, state: State): Promise<void> {
28  await $.tool.register({ name: TOOL_NAME, description: TOOL_DESCRIPTION, inputSchema: INPUT_SCHEMA })
29  state.declared = true
30}
31
32/** Stores on or off; `on` is refused while gemini-core has no key, and declares the tool at once. */
33async function storeEnabled($: EngineInterface, state: State, enabled: boolean): Promise<string> {
34  if (enabled && !(await $.gemini.settings({ consumer: CONSUMER })).hasKey) return NO_KEY_ON
35  await $.store.set(ENABLED_KEY, enabled)
36  if (enabled) await declareTool($, state)
37  return changeText(enabled)
38}
39
40/**
41 * The conversation for Gemini and its message count. A subagent's call sends
42 * none, because which transcript `$.session.messages()` answers there was not
43 * verified.
44 */
45async function conversation($: EngineInterface, config: Config, e: ToolCallInput): Promise<{ text: string; count: number } | undefined> {
46  if (e.agentId !== undefined) return undefined
47  const messages = await $.session.messages()
48  return { text: renderTranscript(messages, config.maxInputChars), count: messages.length }
49}
50
51/**
52 * gemini-core builds the request and reads each answer; the request is sent
53 * here, again after a 503 while it allows, and with the next key after a 429
54 * or a key error.
55 */
56async function askGemini($: EngineInterface, body: Record<string, unknown>): Promise<Asked> {
57  const prepared = await $.gemini.request({ consumer: CONSUMER, body })
58  if ('error' in prepared) return prepared
59  const started = await $.clock.now()
60  let http = prepared.http
61  for (let attempt = 1; ; attempt++) {
62    const r = await $.http.fetch(http.url, http.init)
63    const read = await $.gemini.read({ http, status: r.status, ok: r.ok, text: r.text, attempt, elapsedMs: (await $.clock.now()) - started, deadlineMs: DEADLINE_MS })
64    if ('answer' in read) return { answer: read.answer, model: prepared.model, tier: prepared.tier }
65    if ('error' in read) return read
66    if ('next' in read) http = read.next
67    else await $.clock.sleep(read.retryInMs)
68  }
69}
70
71async function advise($: EngineInterface, state: State, config: Config, e: ToolCallInput): Promise<ToolCallResult> {
72  if (!(await isEnabled($))) return { deny: 'gemini-advisor is off; the user can turn it on with /gemini-advisor on' }
73  try {
74    const message = messageOf(e as Record<string, unknown>)
75    const sent = await conversation($, config, e)
76    const asked = await askGemini($, buildAdviceBody(sent?.text, message, config.maxOutputTokens))
77    if ('error' in asked) throw new Error(asked.error)
78    const advice = adviceText(asked.answer)
79    state.last = usageText(asked.model, sent?.count, asked.answer)
80    $.ui.toast(asked.tier === 'free' ? `${state.last} · sent to Gemini free tier` : state.last, { timeoutMs: 10_000 })
81    return { result: advice }
82  } catch (err) {
83    state.last = `failed: ${errorText(err)}`
84    return { deny: `Gemini advisor failed: ${errorText(err)}` }
85  }
86}
87
88async function runCommand($: EngineInterface, state: State, args: string): Promise<string> {
89  const command = parseCommand(args)
90  if (command.kind === 'error') return command.text
91  if (command.kind === 'reset') {
92    await $.store.delete(ENABLED_KEY)
93    return RESET_TEXT
94  }
95  if (command.kind === 'set') return storeEnabled($, state, command.enabled)
96  return statusText(await isEnabled($), await $.gemini.settings({ consumer: CONSUMER }), state.last)
97}
98
99export const register: Register = (on, options) => {
100  const config = configFrom(options)
101  const state: State = { guidance: false, declared: false }
102
103  on('session.start', async ($, e, next) => {
104    const r = await next(e)
105    await $.gemini.enroll({ consumer: CONSUMER, defaultModel: DEFAULT_MODEL })
106    await $.command.register({
107      name: 'gemini-advisor',
108      description: 'Gemini advisor: status, on, off, reset; /gemini-core sets the model, thinking and tier (gemini-advisor)',
109      argumentHint: '[on | off | reset]',
110    })
111    state.guidance = await isEnabled($)
112    if (state.guidance) await declareTool($, state)
113    return r
114  })
115
116  // Every window shares the store: a /gemini-advisor on made in another window declares the tool here
117  // before the next turn's first request. The note waits for /clear, as after /gemini-advisor on in this window.
118  on('turn.start', async ($, e, next) => {
119    if (!state.declared && (await isEnabled($))) await declareTool($, state)
120    return next(e)
121  })
122
123  // /clear arrives only through the classic seam; the note follows the setting from there.
124  on('classic.SessionStart', async ($, e, next) => {
125    const r = await next(e)
126    if (e.agent_id === undefined) state.guidance = await isEnabled($)
127    return r
128  })
129
130  on('command.run', { command: 'gemini-advisor' }, async ($, e) => ({ text: await runCommand($, state, String(e.args ?? '')) }))
131
132  // The engine puts a plugin's tool behind ToolSearch, where the model sees
133  // only its name and never the description that says when to call it
134  // (measured on 2.1.277). The system prompt says it instead, at the end of
135  // a section every session has; the text is stable, so the cache holds.
136  on('prompt.section', { name: 'env_info_simple' }, async (_, e, next) => {
137    const r = await next(e)
138    return r.text === null || !state.guidance ? r : { text: `${r.text}\n\n${SYSTEM_GUIDANCE}` }
139  })
140
141  // A literal, so the validator names the tool; it equals TOOL_ID.
142  on('tool.call', { tool: 'mcp__gemini-advisor__advise' }, async ($, e) => advise($, state, config, e))
143}
144

1/** The advise tool as the model sees it, and the question Gemini is asked. */
2import type { EngineInterface } from 'claude-code'
3
4/** Gemini's answer as gemini-core reads it. */
5export type Answer = Extract<Awaited<ReturnType<EngineInterface['gemini']['read']>>, { answer: unknown }>['answer']
6
7export const TOOL_NAME = 'advise'
8
9export const TOOL_ID = `mcp__gemini-advisor__${TOOL_NAME}` as const
10
11export const INPUT_SCHEMA = {
12  type: 'object',
13  properties: {
14    message: {
15      type: 'string',
16      description: 'What you did or are about to do, what you found, and the specific question you want a second opinion on.',
17    },
18  },
19  required: ['message'],
20}
21
22const WHEN = [
23  'The user installed this advisor and wants it used. Calling it at these moments is required, not optional; the user does not have to ask:',
24  '- before you present or start a substantial change or a multi-step plan: call it with the plan, then present the plan;',
25  '- when you are stuck: the same error twice, or an approach that keeps failing;',
26  '- when you choose between two approaches: call it before you give the user your choice;',
27  '- before you tell the user the work is done, with what you did and how you checked it.',
28  'Skip it only for simple, mechanical steps, or when the user said not to use tools. The advice can be wrong: check it against the code before you act on it, and tell the user where you disagree.',
29]
30
31/**
32 * What the model reads about the tool: what it is, and when to call it. It
33 * names no model: the engine keeps the description it first sent for the
34 * whole session (measured on 2.1.278), so a named model would go stale after
35 * a /gemini-core change.
36 */
37export const TOOL_DESCRIPTION = [
38  'Ask Gemini, a second model, for advice. It reads the whole conversation so far, tool calls and outputs included, and your message, and answers with a second opinion.',
39  ...WHEN,
40].join('\n')
41
42/**
43 * The system prompt's note about the tool. The engine lists the tool behind
44 * ToolSearch, so the model would see its name alone; this names the model
45 * nowhere, so a model change does not alter the prompt.
46 */
47export const SYSTEM_GUIDANCE = [
48  '# Gemini advisor',
49  `You have a second-opinion tool, ${TOOL_ID}: Gemini reads the whole conversation so far, tool calls and outputs included, and your message, and answers with advice. When it is listed only by name, load it with ToolSearch (query "select:${TOOL_ID}").`,
50  ...WHEN,
51].join('\n')
52
53export const ADVISOR_TASK = `You advise a coding agent (Claude, in Claude Code) that is working with a user. Below is its conversation so far: the user's messages, the agent's replies, and each tool call it made with the output. After it, the agent asks you for advice.
54
55Give a second opinion the agent can act on:
56- Answer the agent's question directly first.
57- Point out mistakes, risks, missed steps and wrong assumptions, each with the evidence in the conversation (a file, an output, a user message).
58- Say so when the plan or the work is sound; do not invent problems.
59- Prefer concrete next steps over general advice. Keep it short.
60- Do not state as fact anything the conversation does not show; say what the agent should check instead.
61- Answer in the language of the agent's message.`
62
63/** The generateContent body asking for advice on the agent's message, with the conversation when there is one. */
64export function buildAdviceBody(transcript: string | undefined, message: string, maxOutputTokens: number): Record<string, unknown> {
65  const conversation = transcript === undefined ? 'The conversation is not available; only the agent\'s message is.' : `The conversation:\n\n${transcript}`
66  return {
67    contents: [{ role: 'user', parts: [{ text: `${ADVISOR_TASK}\n\n${conversation}\n\nThe agent asks:\n\n${message}` }] }],
68    generationConfig: { maxOutputTokens },
69  }
70}
71
72/** The advice; an empty one or one Gemini cut at its output limit throws. */
73export function adviceText(answer: Answer): string {
74  if (answer.finishReason === 'MAX_TOKENS') throw new Error('the advice hit the output token limit (raise maxOutputTokens)')
75  const text = answer.text.trim()
76  if (text === '') throw new Error('the advice is empty')
77  return text
78}
79
80/** The model's message from the tool input; a missing or empty one throws. */
81export function messageOf(input: Record<string, unknown>): string {
82  const message = input.message
83  if (typeof message !== 'string' || message.trim() === '') throw new Error('message is required: what you did and the question')
84  return message.trim()
85}
86
87function tokens(n: number): string {
88  return n >= 1000 ? `${Math.round(n / 1000)}k` : String(n)
89}
90
91/** `asked gemini-3.8-flash · 58 messages · 312k in, 1k out`; `message only` when no conversation was sent. */
92export function usageText(model: string, messages: number | undefined, answer: Answer): string {
93  const sent = messages === undefined ? 'message only' : `${messages} messages`
94  return `asked ${model} · ${sent} · ${tokens(answer.inputTokens)} in, ${tokens(answer.outputTokens)} out`
95}
96

1/** The setting /gemini-advisor changes, and the reading of its argument. */
2import type { EngineInterface } from 'claude-code'
3
4/** What gemini-core says this mod runs with. */
5export type GeminiSettings = Awaited<ReturnType<EngineInterface['gemini']['settings']>>
6
7export type Command = { kind: 'status' } | { kind: 'reset' } | { kind: 'set'; enabled: boolean } | { kind: 'error'; text: string }
8
9export const USAGE = 'expects on, off, or reset; /gemini-core sets the model, the thinking level and the tier'
10
11/** The store key of the on/off setting. */
12export const ENABLED_KEY = 'enabled'
13
14const WORDS: Record<string, Command> = {
15  '': { kind: 'status' },
16  status: { kind: 'status' },
17  reset: { kind: 'reset' },
18  on: { kind: 'set', enabled: true },
19  off: { kind: 'set', enabled: false },
20}
21
22/** Reads the argument of /gemini-advisor. */
23export function parseCommand(args: string): Command {
24  return WORDS[args.trim()] ?? { kind: 'error', text: USAGE }
25}
26
27/** What `on` answers while gemini-core has no key; nothing is stored. */
28export const NO_KEY_ON = 'still off: gemini-core has no Gemini key. Set GEMINI_API_KEY or the gemini-core apiKey option, restart Claude Code, then run /gemini-advisor on'
29
30/** What `reset` answers: the advisor is off until it is turned on. */
31export const RESET_TEXT = 'off: back to the default; /gemini-advisor on turns it on'
32
33/**
34 * The line /gemini-advisor prints for a change. The system prompt note only
35 * changes at a session start or /clear, so the prompt cache holds.
36 */
37export function changeText(enabled: boolean): string {
38  return enabled
39    ? 'on: the advise tool is available now; the system prompt note that says when to call it comes at /clear or the next session'
40    : 'off: a call answers that the advisor is off; the note leaves at /clear or the next session, the tool at the next session'
41}
42
43/** The status of /gemini-advisor, with what gemini-core says it runs with. */
44export function statusText(enabled: boolean, s: GeminiSettings, last: string | undefined): string {
45  const key = s.hasKey ? 'key set' : 'no key: set GEMINI_API_KEY or the gemini-core apiKey option'
46  const lines = [`${enabled ? 'on' : 'off'} · ${s.model} · thinking ${s.thinking ?? 'model default'} · ${s.tier} tier · ${key}`]
47  if (!enabled) lines.push('off until /gemini-advisor on; the model, the thinking level and the tier are /gemini-core settings')
48  if (last !== undefined) lines.push(`last: ${last}`)
49  return lines.join('\n')
50}
51

1/** The plugin options with their defaults. */
2import type { PluginOptions } from 'claude-code'
3
4export type Config = { maxInputChars: number; maxOutputTokens: number }
5
6export const DEFAULTS: Config = { maxInputChars: 2_000_000, maxOutputTokens: 8192 }
7
8/** The plugin name gemini-core knows this mod by, and the model it uses until /gemini-core sets another. */
9export const CONSUMER = 'gemini-advisor'
10export const DEFAULT_MODEL = 'gemini-3.8-flash'
11
12/**
13 * No new Gemini attempt starts once this much has passed. The engine serves
14 * the tool with a 60 s timeout (debug log), and one Gemini answer took 12 s
15 * (measured), so the last attempt still fits.
16 */
17export const DEADLINE_MS = 40_000
18
19function numberOption(options: PluginOptions, key: string, fallback: number, min: number, max: number): number {
20  const value = options[key]
21  return typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max ? value : fallback
22}
23
24/** The plugin options, each out-of-range or missing one replaced by its default. */
25export function configFrom(options: PluginOptions): Config {
26  return {
27    maxInputChars: numberOption(options, 'maxInputChars', DEFAULTS.maxInputChars, 10_000, 4_000_000),
28    maxOutputTokens: numberOption(options, 'maxOutputTokens', DEFAULTS.maxOutputTokens, 256, 65_536),
29  }
30}
31

1/** The conversation as Gemini reads it, cut to a character limit. */
2import type { SessionMessage, ToolUseSummary } from 'claude-code'
3
4/** The output of each tool call, by tool_use_id: its result block, else the call's own text. */
5function outputs(messages: readonly SessionMessage[]): Map<string, { text: string; isError: boolean }> {
6  const out = new Map<string, { text: string; isError: boolean }>()
7  for (const m of messages) {
8    for (const use of m.toolUses) out.set(use.tool_use_id, { text: use.text ?? '', isError: use.isError === true })
9  }
10  for (const m of messages) {
11    for (const r of m.toolResults ?? []) out.set(r.tool_use_id, { text: r.text, isError: r.isError })
12  }
13  return out
14}
15
16/** Cuts a text to about `max` characters: its head and its tail around one note. */
17export function clip(text: string, max: number): string {
18  if (text.length <= max) return text
19  const half = Math.max(0, Math.floor(max / 2))
20  return `${text.slice(0, half)}\n[… ${text.length - 2 * half} chars omitted …]\n${text.slice(text.length - half)}`
21}
22
23function callLines(use: ToolUseSummary, output: { text: string; isError: boolean } | undefined, cap: number): string[] {
24  const status = output?.isError === true ? 'error' : 'output'
25  return [`  [call] ${use.tool} ${JSON.stringify(use.input) ?? '{}'}`, `  ${status}: ${clip(output?.text ?? '', cap)}`]
26}
27
28function render(messages: readonly SessionMessage[], byUse: ReadonlyMap<string, { text: string; isError: boolean }>, cap: number): string {
29  const lines: string[] = []
30  messages.forEach((m, i) => {
31    lines.push(`#${i + 1} ${m.role}: ${m.text}`)
32    for (const use of m.toolUses) lines.push(...callLines(use, byUse.get(use.tool_use_id), cap))
33  })
34  return lines.join('\n')
35}
36
37/** The longest output length that makes the transcript fit, found by bisection. */
38function outputCap(fixed: number, lengths: readonly number[], max: number): number | undefined {
39  const size = (cap: number): number => fixed + lengths.reduce((sum, n) => sum + Math.min(n, cap + 40), 0)
40  if (size(0) > max) return undefined
41  let low = 0
42  let high = Math.max(0, ...lengths)
43  while (low < high) {
44    const mid = Math.ceil((low + high) / 2)
45    if (size(mid) <= max) low = mid
46    else high = mid - 1
47  }
48  return low
49}
50
51/**
52 * Every message in order, each tool call with its input and output. Over
53 * `maxChars`, the longest outputs are cut to one common length; a
54 * conversation over it without any output throws.
55 */
56export function renderTranscript(messages: readonly SessionMessage[], maxChars: number): string {
57  const byUse = outputs(messages)
58  const full = render(messages, byUse, Infinity)
59  if (full.length <= maxChars) return full
60  const lengths = messages.flatMap(m => m.toolUses.map(u => byUse.get(u.tool_use_id)?.text.length ?? 0))
61  const fixed = full.length - lengths.reduce((a, b) => a + b, 0)
62  const cap = outputCap(fixed, lengths, maxChars)
63  if (cap === undefined) throw new Error(`the conversation is over ${maxChars} characters even without tool output`)
64  return render(messages, byUse, cap)
65}
66