ethagent 1.1.1 → 2.0.0

package/src/providers/gemini.ts

@@ -1,17 +1,32 @@
 import { getKey } from '../storage/secrets.js'
-import type { Message, Provider, ProviderCompleteOptions, StreamEvent } from './contracts.js'
+import type { Message, MessageContentBlock, Provider, ProviderCompleteOptions, StreamEvent } from './contracts.js'
 import { ProviderError } from './contracts.js'
 import { providerErrorFromResponse } from './errors.js'
 import { fetchWithRetryStreamEvents } from './retry.js'
 import { iterSseFrames } from './sse.js'
-import { messageTextContent } from '../utils/messages.js'
+
+export type GeminiToolDefinition = {
+  name: string
+  description: string
+  parameters: {
+    type: 'object'
+    properties?: Record<string, unknown>
+    required?: string[]
+  }
+}
+
+type GeminiPart = {
+  text?: string
+  functionCall?: {
+    name?: string
+    args?: Record<string, unknown>
+  }
+}
 
 type GeminiChunk = {
   candidates?: Array<{
     content?: {
-      parts?: Array<{
-        text?: string
-      }>
+      parts?: GeminiPart[]
     }
     finishReason?: string
   }>
@@ -24,15 +39,45 @@ type GeminiChunk = {
   }
 }
 
+type GeminiContentPart =
+  | { text: string }
+  | { functionCall: { name: string; args: Record<string, unknown> } }
+  | { functionResponse: { name: string; response: Record<string, unknown> } }
+
+type GeminiContent = {
+  role: 'user' | 'model'
+  parts: GeminiContentPart[]
+}
+
+type GeminiPayload = {
+  contents: GeminiContent[]
+  systemInstruction?: { parts: Array<{ text: string }> }
+  generationConfig?: { maxOutputTokens?: number }
+  tools?: Array<{ functionDeclarations: GeminiToolDefinition[] }>
+  toolConfig?: { functionCallingConfig: { mode: 'AUTO' } }
+}
+
+type DoneStopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'unknown'
+
 const READ_TIMEOUT_MS = 45_000
 
+export type GeminiQuotaInfo = {
+  retryAfterMs?: number
+  metric?: string
+  quotaValue?: string
+  quotaId?: string
+}
+
 export class GeminiProvider implements Provider {
   readonly id = 'gemini' as const
   readonly model: string
-  readonly supportsTools = false
+  readonly supportsTools: boolean
+  private readonly tools: GeminiToolDefinition[]
 
-  constructor(opts: { model: string }) {
+  constructor(opts: { model: string; tools?: GeminiToolDefinition[] }) {
     this.model = opts.model
+    this.tools = opts.tools ?? []
+    this.supportsTools = this.tools.length > 0
   }
 
   async *complete(
@@ -40,16 +85,17 @@ export class GeminiProvider implements Provider {
     signal: AbortSignal,
     options: ProviderCompleteOptions = {},
   ): AsyncIterable<StreamEvent> {
-    const apiKey = await getKey('gemini')
+    const rawApiKey = await getKey('gemini')
+    const apiKey = rawApiKey?.trim()
     if (!apiKey) {
       const error = new ProviderError('missing API key for gemini (/doctor to verify)')
       yield { type: 'error', message: error.message }
       return
     }
 
-    const payload = buildGeminiPayload(messages, options)
+    const payload = buildGeminiPayload(messages, this.tools, options)
     const modelName = this.model.replace(/^models\//, '')
-    const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(modelName)}:streamGenerateContent?alt=sse&key=${encodeURIComponent(apiKey)}`
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(modelName)}:streamGenerateContent?alt=sse`
 
     let response: Response
     try {
@@ -58,6 +104,7 @@ export class GeminiProvider implements Provider {
         headers: {
           'content-type': 'application/json',
           accept: 'text/event-stream',
+          'x-goog-api-key': apiKey,
         },
         body: JSON.stringify(payload),
       }, { signal })
@@ -79,6 +126,9 @@ export class GeminiProvider implements Provider {
 
     let inputTokens: number | undefined
     let outputTokens: number | undefined
+    let stopReason: DoneStopReason = 'unknown'
+    let toolCallIndex = 0
+    let sawToolCall = false
 
     try {
       for await (const frame of iterSseFrames(response.body, signal, READ_TIMEOUT_MS)) {
@@ -94,9 +144,26 @@ export class GeminiProvider implements Provider {
           throw new ProviderError(`prompt blocked: ${blockedReason.toLowerCase()}`)
         }
 
-        const parts = parsed.candidates?.[0]?.content?.parts ?? []
+        const candidate = parsed.candidates?.[0]
+        const parts = candidate?.content?.parts ?? []
         for (const part of parts) {
-          if (part.text) yield { type: 'text', delta: part.text }
+          if (part.text) {
+            yield { type: 'text', delta: part.text }
+            continue
+          }
+          if (part.functionCall?.name) {
+            const id = `gemini-tool-${toolCallIndex}`
+            toolCallIndex += 1
+            sawToolCall = true
+            const name = part.functionCall.name
+            const input = part.functionCall.args ?? {}
+            yield { type: 'tool_use_start', id, name }
+            yield { type: 'tool_use_stop', id, name, input }
+          }
+        }
+
+        if (candidate?.finishReason) {
+          stopReason = normalizeFinishReason(candidate.finishReason, sawToolCall)
         }
 
         inputTokens = parsed.usageMetadata?.promptTokenCount ?? inputTokens
@@ -109,44 +176,190 @@ export class GeminiProvider implements Provider {
     }
 
     if (signal.aborted) return
-    yield { type: 'done', inputTokens, outputTokens }
+    if (sawToolCall) stopReason = 'tool_use'
+    yield { type: 'done', inputTokens, outputTokens, stopReason }
   }
 }
 
-function buildGeminiPayload(messages: Message[], options: ProviderCompleteOptions = {}): {
-  contents: Array<{
-    role: 'user' | 'model'
-    parts: Array<{ text: string }>
-  }>
-  systemInstruction?: {
-    parts: Array<{ text: string }>
-  }
-  generationConfig?: {
-    maxOutputTokens?: number
-  }
-} {
+export function buildGeminiPayload(
+  messages: Message[],
+  tools: GeminiToolDefinition[] = [],
+  options: ProviderCompleteOptions = {},
+): GeminiPayload {
   const systemParts: string[] = []
-  const contents: Array<{
-    role: 'user' | 'model'
-    parts: Array<{ text: string }>
-  }> = []
+  const contents: GeminiContent[] = []
+  const toolUseNamesById = new Map<string, string>()
 
   for (const message of messages) {
-    const text = messageTextContent(message).trim()
-    if (!text) continue
+    const blocks = normalizeBlocks(message.content)
+    if (blocks.length === 0) continue
+
     if (message.role === 'system') {
-      systemParts.push(text)
+      const systemText = blocks
+        .filter((block): block is Extract<MessageContentBlock, { type: 'text' }> => block.type === 'text')
+        .map(block => block.text)
+        .join('\n\n')
+        .trim()
+      if (systemText) systemParts.push(systemText)
+      continue
+    }
+
+    if (message.role === 'assistant') {
+      const parts: GeminiContentPart[] = []
+      for (const block of blocks) {
+        if (block.type === 'text') {
+          parts.push({ text: block.text })
+        } else if (block.type === 'tool_use') {
+          toolUseNamesById.set(block.id, block.name)
+          parts.push({ functionCall: { name: block.name, args: block.input } })
+        }
+      }
+      if (parts.length > 0) contents.push({ role: 'model', parts })
       continue
     }
-    contents.push({
-      role: message.role === 'assistant' ? 'model' : 'user',
-      parts: [{ text }],
-    })
+
+    const parts: GeminiContentPart[] = []
+    for (const block of blocks) {
+      if (block.type === 'text') {
+        parts.push({ text: block.text })
+      } else if (block.type === 'tool_result') {
+        const name = toolUseNamesById.get(block.toolUseId) ?? 'unknown'
+        const response: Record<string, unknown> = block.isError
+          ? { content: block.content, isError: true }
+          : { content: block.content }
+        parts.push({ functionResponse: { name, response } })
+      }
+    }
+    if (parts.length > 0) contents.push({ role: 'user', parts })
   }
 
+  const payload: GeminiPayload = { contents }
+  if (systemParts.length > 0) {
+    payload.systemInstruction = { parts: [{ text: systemParts.join('\n\n') }] }
+  }
+  if (options.maxTokens) {
+    payload.generationConfig = { maxOutputTokens: options.maxTokens }
+  }
+  if (tools.length > 0) {
+    payload.tools = [{ functionDeclarations: tools }]
+    payload.toolConfig = { functionCallingConfig: { mode: 'AUTO' } }
+  }
+  return payload
+}
+
+function normalizeBlocks(content: Message['content']): MessageContentBlock[] {
+  if (typeof content === 'string') {
+    const text = content.trim()
+    return text ? [{ type: 'text', text }] : []
+  }
+  return content.filter(block => {
+    if (block.type === 'text') return block.text.trim().length > 0
+    return true
+  })
+}
+
+function normalizeFinishReason(reason: string, sawToolCall: boolean): DoneStopReason {
+  if (sawToolCall) return 'tool_use'
+  switch (reason) {
+    case 'STOP':
+      return 'end_turn'
+    case 'MAX_TOKENS':
+      return 'max_tokens'
+    case 'STOP_SEQUENCE':
+      return 'stop_sequence'
+    default:
+      return 'unknown'
+  }
+}
+
+type GeminiQuotaInfoInternal = GeminiQuotaInfo & { kind: 'quota-failure' | 'rate-limit' }
+
+function readGeminiQuotaInfo(bodyText: string): GeminiQuotaInfoInternal | undefined {
+  let body: unknown
+  try {
+    body = JSON.parse(bodyText)
+  } catch {
+    return undefined
+  }
+  if (Array.isArray(body)) body = body[0]
+  if (!body || typeof body !== 'object') return undefined
+
+  const error = (body as { error?: unknown }).error
+  if (!error || typeof error !== 'object') return undefined
+
+  const details = (error as { details?: unknown }).details
+  if (!Array.isArray(details)) return undefined
+
+  let retryAfterMs: number | undefined
+  let metric: string | undefined
+  let quotaValue: string | undefined
+  let quotaId: string | undefined
+  let isQuotaFailure = false
+
+  for (const detail of details) {
+    if (!detail || typeof detail !== 'object') continue
+    const type = (detail as { '@type'?: unknown })['@type']
+    if (typeof type !== 'string') continue
+
+    if (/RetryInfo$/.test(type)) {
+      const delay = (detail as { retryDelay?: unknown }).retryDelay
+      const parsed = parseGoogleDurationMs(delay)
+      if (parsed !== undefined) retryAfterMs = parsed
+    } else if (/QuotaFailure$/.test(type)) {
+      isQuotaFailure = true
+      const violations = (detail as { violations?: unknown }).violations
+      if (Array.isArray(violations) && violations.length > 0) {
+        const first = violations[0] as Record<string, unknown> | undefined
+        if (first) {
+          const m = first.metric
+          const qv = first.quotaValue
+          const qi = first.quotaId
+          if (typeof m === 'string') metric = m
+          if (typeof qv === 'string') quotaValue = qv
+          if (typeof qi === 'string') quotaId = qi
+        }
+      }
+    }
+  }
+
+  if (!isQuotaFailure && retryAfterMs === undefined) return undefined
   return {
-    contents,
-    systemInstruction: systemParts.length > 0 ? { parts: [{ text: systemParts.join('\n\n') }] } : undefined,
-    generationConfig: options.maxTokens ? { maxOutputTokens: options.maxTokens } : undefined,
+    kind: isQuotaFailure ? 'quota-failure' : 'rate-limit',
+    retryAfterMs,
+    metric,
+    quotaValue,
+    quotaId,
+  }
+}
+
+function parseGoogleDurationMs(value: unknown): number | undefined {
+  if (typeof value !== 'string') return undefined
+  const m = /^(\d+(?:\.\d+)?)s$/.exec(value.trim())
+  if (!m) return undefined
+  const seconds = Number(m[1])
+  return Number.isFinite(seconds) ? Math.round(seconds * 1000) : undefined
+}
+
+export async function formatGeminiRateLimitMessage(response: Response): Promise<string | undefined> {
+  let bodyText = ''
+  try { bodyText = await response.text() } catch { return undefined }
+  const info = readGeminiQuotaInfo(bodyText)
+  if (!info) return undefined
+  const exhausted = info.kind === 'quota-failure'
+  const isFreeTier = info.metric ? /free_tier/i.test(info.metric) : false
+  const parts = [exhausted ? 'gemini quota hit' : 'gemini rate limit']
+  if (info.quotaValue) {
+    parts.push(isFreeTier ? `(free-tier cap: ${info.quotaValue})` : `(cap: ${info.quotaValue})`)
+  } else if (isFreeTier) {
+    parts.push('(free-tier cap)')
+  }
+  if (info.retryAfterMs !== undefined) {
+    const seconds = Math.ceil(info.retryAfterMs / 1000)
+    parts.push(`— retry in ~${seconds}s`)
+  } else if (exhausted && isFreeTier) {
+    parts.push('— enable billing on the API key\'s project, or /model to switch')
+  } else if (exhausted) {
+    parts.push('— /model to switch providers, or wait for the quota window to reset')
   }
+  return parts.join(' ')
 }

package/src/providers/registry.ts

@@ -6,7 +6,7 @@ import type { SessionMode } from '../runtime/sessionMode.js'
 import { AnthropicProvider } from './anthropic.js'
 import { GeminiProvider } from './gemini.js'
 import { OpenAIChatProvider } from './openai-chat.js'
-import { anthropicTools, openAITools } from '../tools/registry.js'
+import { anthropicTools, geminiTools, openAITools } from '../tools/registry.js'
 import { openAIBaseUrlFor } from '../models/catalog.js'
 import type { Tool } from '../tools/contracts.js'
 
@@ -37,6 +37,6 @@ export function createProvider(config: EthagentConfig, options: { mode?: Session
     case 'anthropic':
       return new AnthropicProvider({ model: config.model, tools: anthropicTools(mode, toolContext) })
     case 'gemini':
-      return new GeminiProvider({ model: config.model })
+      return new GeminiProvider({ model: config.model, tools: geminiTools(mode, toolContext) })
   }
 }

package/src/providers/retry.ts

@@ -54,5 +54,5 @@ export async function* fetchWithRetryStreamEvents(
   await fetchPromise
   if (settled?.state === 'resolved') return settled.response
   if (settled?.state === 'rejected') throw settled.error
-  throw new Error('fetch retry completed without a response')
+  throw new Error('Fetch retry completed without a response')
 }

package/src/runtime/sessionMode.ts

@@ -24,7 +24,7 @@ export function nextSessionMode(mode: SessionMode): SessionMode {
 }
 
 export function sessionModeLabel(mode: SessionMode): string {
-  return mode === 'plan' ? 'plan mode' : mode === 'accept-edits' ? 'accept edits on' : ''
+  return mode === 'plan' ? 'Plan mode' : mode === 'accept-edits' ? 'Accept edits on' : ''
 }
 
 export function modePolicy(mode: PolicyMode): ModePolicy {

package/src/runtime/systemPrompt.ts

@@ -98,6 +98,7 @@ function buildToolEnabledPrompt(ctx: SystemPromptContext): string {
                   ]
                 : ['No agent identity is linked in this session. Do not attempt private identity continuity edits; ask the user to create or load an agent first.']),
               'Use `run_bash` **only** when true shell execution is necessary.',
+              'Never use `run_bash` to produce conversational text. Do not call `echo`, `printf`, or similar to emit your reply — write it as your assistant text. Bash is for actions that need a real shell, not for generating words.',
               '**CWD CONTINUITY**: The working directory below is authoritative. After `change_directory` succeeds, use the new path as the base for subsequent actions.',
               'Do not lag behind the CWD. Edit/read relative to the *current* working directory.',
               'If asked for a complete application/site/game, **create the files yourself**. Do not hand back copy-paste templates.',
@@ -112,6 +113,7 @@ function buildToolEnabledPrompt(ctx: SystemPromptContext): string {
           'Local Model Tool Discipline',
           [
             '**PROTOCOL**: Emit tool calls in the native tool-call protocol. Do NOT describe the call in prose first, and do NOT print a JSON blob inside markdown as a substitute for an actual tool call.',
+            '**NO ECHO REPLIES**: Never call `run_bash` with `echo`, `printf`, or any command whose only purpose is to print your reply. Reply directly in your assistant text. Bash is for real shell actions only.',
             '**NO FAKE COMPLETIONS**: NEVER claim you have updated or created a file if you have not used the edit tools. Talk is cheap, use the tools.',
             'One tool call per response when a tool is needed. Wait for the tool result before deciding the next step.',
             ...(ctx.hasIdentity

package/src/runtime/toolExecution.ts

@@ -24,10 +24,6 @@ import {
 import type { MessageRow } from '../chat/MessageList.js'
 import { modePolicy, toPermissionMode, type SessionMode } from './sessionMode.js'
 
-// ---------------------------------------------------------------------------
-// Tool execution with permission gating
-// ---------------------------------------------------------------------------
-
 export type ToolExecutorOptions = {
   name: string
   input: Record<string, unknown>
@@ -188,10 +184,6 @@ function formatToolParseError(err: unknown, toolName?: string): string {
   return withToolHint((err as Error).message || 'tool input did not match the required schema')
 }
 
-// ---------------------------------------------------------------------------
-// Pending tool-use runner (per turn)
-// ---------------------------------------------------------------------------
-
 export type PendingToolUse = {
   id: string
   name: string
@@ -239,9 +231,16 @@ export async function runPendingToolUses(args: {
   const completedTools: CompletedToolUse[] = []
 
   for (const toolUse of args.pendingToolUses) {
+    const rowId = args.nextRowId()
     args.updateRows(prev => [
       ...prev,
-      { role: 'tool_use', id: args.nextRowId(), name: toolUse.name, summary: toolUse.name, input: summarizeToolInput(toolUse.input) },
+      {
+        role: 'tool_call',
+        id: rowId,
+        name: toolUse.name,
+        summary: toolUse.name,
+        input: summarizeToolInput(toolUse.input),
+      },
     ])
     await args.persistTurnMessage({
       version: 2,
@@ -266,7 +265,7 @@ export async function runPendingToolUses(args: {
     }
 
     await args.applySessionRule(sessionRule, persistRule)
-    await recordToolResult(args, toolUse, result)
+    await recordToolResult(args, toolUse, result, rowId)
   }
 
   return { cancelled: false, completedTools }
@@ -279,25 +278,22 @@ async function recordToolResult(
   >,
   toolUse: PendingToolUse,
   result: ToolResult,
+  rowId: string,
 ): Promise<void> {
-  args.updateRows(prev => [
-    ...prev,
-    {
-      role: 'tool_result',
-      id: args.nextRowId(),
-      name: toolUse.name,
-      summary: result.summary,
-      content: toolResultContentForRow(toolUse.name, result.content, !result.ok),
-      isError: !result.ok,
-    },
-  ])
+  const isError = !result.ok
+  const resultContent = toolResultContentForRow(toolUse.name, result.content, isError)
+  args.updateRows(prev => prev.map(row =>
+    row.role === 'tool_call' && row.id === rowId
+      ? { ...row, result: { content: resultContent, summary: result.summary, isError } }
+      : row,
+  ))
   await args.persistTurnMessage({
     version: 2,
     role: 'tool_result',
     toolUseId: toolUse.id,
     name: toolUse.name,
     content: result.content,
-    isError: !result.ok,
+    isError,
     createdAt: args.nowIso(),
     turnId: args.turnId,
   })

package/src/runtime/toolIntent.ts

@@ -8,18 +8,6 @@ export type ToolIntent = {
   reason: string
 }
 
-/**
- * detectDirectToolIntent — typed detection for high-confidence direct
- * filesystem requests. Returns the first matching intent, or null for
- * ambiguous or multi-step engineering requests so the model handles those.
- *
- * Covers:
- *   - change_directory: "cd into identity", "go to src/identity"
- *   - list_directory: "list files", "show what's here", "ls"
- *   - read_file: "read package.json", "open/show/cat <file>"
- *
- * Returns null for anything else.
- */
 export function detectDirectToolIntent(userText: string): ToolIntent | null {
   const uses = directToolUsesForUserText(userText)
   if (uses.length === 0) return null
@@ -28,14 +16,6 @@ export function detectDirectToolIntent(userText: string): ToolIntent | null {
   return { name: first.name, input: first.input, reason }
 }
 
-/**
- * validateAssistantTextAgainstTurnEvidence — checks whether assistant prose
- * claims workspace state that isn't backed by a tool result from the active
- * turn.
- *
- * Returns 'ok' if the text is safe (no unsupported claims), or 'needs-tool'
- * if the text claims state that has no matching tool evidence.
- */
 export function validateAssistantTextAgainstTurnEvidence(
   text: string,
   evidence: ToolEvidence[],