app/agent/geminiBackend.ts

// Google AI Studio (Gemini API) as a remote alternative to local
// Ollama -- mainly to isolate how much of this project's slowness is
// local-model compute vs. the surrounding system, since a production-
// grade remote serving stack removes the local-hardware variable
// entirely. Verified request/response shape directly against Google's
// own API reference (contents[]/parts[], systemInstruction,
// functionCall/functionResponse) rather than assumed.
import type { ChatBackend, ChatMessage } from "./chatBackend.js";
import type { ToolDef } from "./tools.js";

function apiKey(): string {
  const key = process.env.GEMINI_API_KEY ?? process.env.GOOGLE_AI_API_KEY;
  if (!key) throw new Error('Gemini backend needs an API key: set GEMINI_API_KEY (or GOOGLE_AI_API_KEY) in your environment or app/.env. Get a free-tier key at https://aistudio.google.com/apikey -- never paste the key itself into chat.');
  return key;
}

function toGeminiTools(tools: ToolDef[]) {
  return [{ functionDeclarations: tools.map((t) => ({ name: t.name, description: t.description, parameters: t.parameters })) }];
}

interface GeminiPart {
  text?: string;
  functionCall?: { name: string; args: Record<string, unknown>; thoughtSignature?: string };
  functionResponse?: { name: string; response: Record<string, unknown> };
}

// Gemini has no "system" role and no "tool" role: the system message
// becomes systemInstruction (pulled out separately, never part of
// contents[]), and a tool result becomes a "user"-role functionResponse
// part -- its own real convention, not a guess, per the verified docs.
function toGeminiContents(messages: ChatMessage[]): { systemInstruction: { parts: GeminiPart[] } | undefined; contents: { role: string; parts: GeminiPart[] }[] } {
  let systemInstruction: { parts: GeminiPart[] } | undefined;
  const contents: { role: string; parts: GeminiPart[] }[] = [];
  for (const m of messages) {
    if (m.role === "system") {
      systemInstruction = { parts: [{ text: m.content }] };
      continue;
    }
    if (m.role === "tool") {
      let response: Record<string, unknown>;
      try {
        response = JSON.parse(m.content);
      } catch {
        response = { result: m.content };
      }
      contents.push({ role: "user", parts: [{ functionResponse: { name: m.name ?? "unknown", response } }] });
      continue;
    }
    const parts: GeminiPart[] = [];
    if (m.content) parts.push({ text: m.content });
    for (const call of m.tool_calls ?? []) {
      // Prefer replaying the exact functionCall part Gemini gave us
      // (thoughtSignature and all) over reconstructing one -- a
      // reconstructed call missing thoughtSignature is a real,
      // confirmed 400 from the API, not just a quality nit.
      const raw = call.raw as GeminiPart["functionCall"] | undefined;
      parts.push({ functionCall: raw ?? { name: call.function.name, args: call.function.arguments } });
    }
    contents.push({ role: m.role === "assistant" ? "model" : "user", parts });
  }
  return { systemInstruction, contents };
}

function fromGeminiResponse(data: { candidates?: { content?: { parts?: GeminiPart[] } }[] }): ChatMessage {
  const parts = data.candidates?.[0]?.content?.parts ?? [];
  let content = "";
  const toolCalls: NonNullable<ChatMessage["tool_calls"]> = [];
  for (const p of parts) {
    if (p.text) content += p.text;
    if (p.functionCall) toolCalls.push({ function: { name: p.functionCall.name, arguments: p.functionCall.args }, raw: p.functionCall });
  }
  return { role: "assistant", content, tool_calls: toolCalls.length ? toolCalls : undefined };
}

export function createGeminiBackend(model: string): ChatBackend {
  // Resolved eagerly, not inside chat() -- callers (zz work/--assist)
  // call this before resolveCliBackendMode/enterFullscreen,
  // specifically so a missing key fails fast as a plain CLI error
  // instead of surfacing deep inside a TUI session on the first draft
  // attempt.
  const key = apiKey();
  return {
    name: `gemini:${model}`,
    async chat(messages, tools, onPartial) {
      const { systemInstruction, contents } = toGeminiContents(messages);
      const res = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`, {
        method: "POST",
        headers: { "content-type": "application/json", "x-goog-api-key": key },
        body: JSON.stringify({ contents, systemInstruction, ...(tools.length ? { tools: toGeminiTools(tools) } : {}) }),
      });
      if (!res.ok) throw new Error(`gemini chat failed: ${res.status} ${await res.text()}`);
      const data = await res.json();
      const message = fromGeminiResponse(data);
      // No streaming here yet (this call is non-streaming) -- still
      // report the final content once, so callers that only care about
      // "what's the latest text" (a TUI status line) don't need a
      // separate non-streaming code path.
      if (message.content) onPartial?.(message.content);
      return message;
    },
  };
}