@jay-framework/gemini-agent-plugin 0.12.0

package/dist/actions/send-message.jay-action

@@ -0,0 +1,26 @@
+name: sendMessage
+description: Send a user message to the Gemini agent. Includes conversation history, page automation tool definitions, and current page state. Returns either a text response or pending tool calls.
+
+inputSchema:
+  message: string
+  history:
+    - role: string
+      parts:
+        - {}
+  toolDefinitions:
+    - name: string
+      description: string
+      inputSchema: {}
+      category: string
+  pageState: {}
+
+outputSchema:
+  type: string
+  message?: string
+  calls?:
+    - id: string
+      name: string
+      args: {}
+      category: string
+  history:
+    - {}

package/dist/actions/submit-tool-results.jay-action

@@ -0,0 +1,29 @@
+name: submitToolResults
+description: Submit tool execution results back to continue the Gemini conversation. Called after the client executes page automation tools. Returns either a text response or more pending tool calls.
+
+inputSchema:
+  results:
+    - callId: string
+      result: string
+      isError: boolean
+  history:
+    - role: string
+      parts:
+        - {}
+  toolDefinitions:
+    - name: string
+      description: string
+      inputSchema: {}
+      category: string
+  pageState: {}
+
+outputSchema:
+  type: string
+  message?: string
+  calls?:
+    - id: string
+      name: string
+      args: {}
+      category: string
+  history:
+    - {}

package/dist/contracts/gemini-chat.jay-contract

@@ -0,0 +1,69 @@
+name: gemini-chat
+description: AI chat agent powered by Gemini with page automation capabilities
+tags:
+  # Message list — repeated sub-contract for full chat history
+  - tag: messages
+    type: sub-contract
+    repeated: true
+    trackBy: index
+    phase: fast+interactive
+    tags:
+      - tag: index
+        type: data
+        dataType: number
+      - tag: role
+        type: [data, variant]
+        dataType: enum (user | assistant)
+      - tag: content
+        type: data
+        dataType: string
+
+  # Compact mode shortcuts — avoid iterating full list
+  - tag: lastUserMessage
+    type: data
+    dataType: string
+    phase: fast+interactive
+  - tag: lastAssistantMessage
+    type: data
+    dataType: string
+    phase: fast+interactive
+
+  # Chat input
+  - tag: messageInput
+    type: [data, interactive]
+    dataType: string
+    elementType: HTMLInputElement
+
+  # Send button
+  - tag: sendMessage
+    type: interactive
+    elementType: HTMLButtonElement
+
+  # Expand/collapse toggle for compact mode
+  - tag: toggleExpand
+    type: interactive
+    elementType: HTMLButtonElement
+
+  # State variants
+  - tag: isLoading
+    type: variant
+    dataType: boolean
+    phase: fast+interactive
+  - tag: isExpanded
+    type: variant
+    dataType: boolean
+    phase: fast+interactive
+  - tag: hasError
+    type: variant
+    dataType: boolean
+    phase: fast+interactive
+  - tag: hasMessages
+    type: variant
+    dataType: boolean
+    phase: fast+interactive
+
+  # Error message
+  - tag: errorMessage
+    type: data
+    dataType: string
+    phase: fast+interactive

package/dist/contracts/gemini-chat.jay-contract.d.ts

@@ -0,0 +1,51 @@
+import {HTMLElementCollectionProxy, HTMLElementProxy, JayContract} from "@jay-framework/runtime";
+
+
+export enum Role {
+  user,
+  assistant
+}
+
+export interface MessageOfGeminiChatViewState {
+  index: number,
+  role: Role,
+  content: string
+}
+
+export interface GeminiChatViewState {
+  messages: Array<MessageOfGeminiChatViewState>,
+  lastUserMessage: string,
+  lastAssistantMessage: string,
+  messageInput: string,
+  isLoading: boolean,
+  isExpanded: boolean,
+  hasError: boolean,
+  hasMessages: boolean,
+  errorMessage: string
+}
+
+export type GeminiChatSlowViewState = {};
+
+export type GeminiChatFastViewState = Pick<GeminiChatViewState, 'lastUserMessage' | 'lastAssistantMessage' | 'messageInput' | 'isLoading' | 'isExpanded' | 'hasError' | 'hasMessages' | 'errorMessage'> & {
+    messages: Array<GeminiChatViewState['messages'][number]>;
+};
+
+export type GeminiChatInteractiveViewState = Pick<GeminiChatViewState, 'lastUserMessage' | 'lastAssistantMessage' | 'messageInput' | 'isLoading' | 'isExpanded' | 'hasError' | 'hasMessages' | 'errorMessage'> & {
+    messages: Array<GeminiChatViewState['messages'][number]>;
+};
+
+
+export interface GeminiChatRefs {
+  messageInput: HTMLElementProxy<GeminiChatViewState, HTMLInputElement>,
+  sendMessage: HTMLElementProxy<GeminiChatViewState, HTMLButtonElement>,
+  toggleExpand: HTMLElementProxy<GeminiChatViewState, HTMLButtonElement>
+}
+
+
+export interface GeminiChatRepeatedRefs {
+  messageInput: HTMLElementCollectionProxy<GeminiChatViewState, HTMLInputElement>,
+  sendMessage: HTMLElementCollectionProxy<GeminiChatViewState, HTMLButtonElement>,
+  toggleExpand: HTMLElementCollectionProxy<GeminiChatViewState, HTMLButtonElement>
+}
+
+export type GeminiChatContract = JayContract<GeminiChatViewState, GeminiChatRefs, GeminiChatSlowViewState, GeminiChatFastViewState, GeminiChatInteractiveViewState>

package/dist/index.client.js

@@ -0,0 +1,242 @@
+import { createJayService, makeJayInit, makeJayStackComponent } from "@jay-framework/fullstack-component";
+import { createSignal, createMemo } from "@jay-framework/component";
+import { createActionCaller } from "@jay-framework/stack-client-runtime";
+const GEMINI_SERVICE = createJayService("GeminiService");
+const init = makeJayInit();
+const callSendMessage = createActionCaller("geminiAgent.sendMessage", "POST");
+const callSubmitToolResults = createActionCaller("geminiAgent.submitToolResults", "POST");
+function buildSerializedTools(automation) {
+  const { interactions } = automation.getPageState();
+  const tools = [];
+  for (const group of interactions) {
+    const sample = group.items[0];
+    if (!sample)
+      continue;
+    const elementType = sample.element.constructor.name;
+    const isFillable = [
+      "HTMLInputElement",
+      "HTMLTextAreaElement",
+      "HTMLSelectElement"
+    ].includes(elementType);
+    const isCheckbox = elementType === "HTMLInputElement" && ["checkbox", "radio"].includes(sample.element.type);
+    const isForEach = group.items.length > 1 || sample.coordinate.length > 1;
+    const prefix = isCheckbox ? "toggle" : isFillable ? "fill" : "click";
+    const toolName = `${prefix}-${toKebab(group.refName)}`;
+    const humanName = toHumanReadable(group.refName);
+    const description = group.description || `${isCheckbox ? "Toggle" : isFillable ? "Fill" : "Click"} ${humanName}${isForEach ? " for a specific item" : ""}`;
+    const properties = {};
+    const required = [];
+    if (isForEach) {
+      properties.coordinate = {
+        type: "string",
+        description: `Item coordinate (e.g. "${sample.coordinate.join("/")}")`
+      };
+      required.push("coordinate");
+    }
+    if (isFillable && !isCheckbox) {
+      properties.value = {
+        type: "string",
+        description: `Value to set in ${humanName}`
+      };
+      required.push("value");
+    }
+    tools.push({
+      name: toolName,
+      description,
+      inputSchema: {
+        type: "object",
+        properties,
+        required: required.length > 0 ? required : void 0
+      },
+      category: "page-automation"
+    });
+  }
+  return tools;
+}
+function toKebab(s) {
+  return s.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+function toHumanReadable(s) {
+  return s.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[-_]/g, " ").toLowerCase();
+}
+function executePageAutomationTool(automation, call) {
+  try {
+    const { interactions } = automation.getPageState();
+    const toolName = call.name;
+    const args = call.args;
+    const parts = toolName.split("-");
+    const prefix = parts[0];
+    const refName = parts.slice(1).join("-");
+    const group = interactions.find((g) => toKebab(g.refName) === refName);
+    if (!group) {
+      return {
+        callId: call.id,
+        result: JSON.stringify({ error: `Interaction '${refName}' not found` }),
+        isError: true
+      };
+    }
+    let item = group.items[0];
+    if (args.coordinate && typeof args.coordinate === "string") {
+      const coord = args.coordinate.split("/");
+      item = group.items.find((i) => i.coordinate.join("/") === args.coordinate) || group.items[0];
+    }
+    if (!item) {
+      return {
+        callId: call.id,
+        result: JSON.stringify({ error: "Item not found" }),
+        isError: true
+      };
+    }
+    if (prefix === "fill" && args.value != null) {
+      const el = item.element;
+      const nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value")?.set;
+      if (nativeInputValueSetter) {
+        nativeInputValueSetter.call(el, String(args.value));
+      } else {
+        el.value = String(args.value);
+      }
+      el.dispatchEvent(new Event("input", { bubbles: true }));
+      el.dispatchEvent(new Event("change", { bubbles: true }));
+    } else {
+      item.element.click();
+    }
+    const newState = automation.getPageState();
+    return {
+      callId: call.id,
+      result: JSON.stringify({ success: true, pageState: newState.viewState })
+    };
+  } catch (error) {
+    return {
+      callId: call.id,
+      result: JSON.stringify({ error: error.message }),
+      isError: true
+    };
+  }
+}
+function GeminiChatInteractive(_props, refs, fastViewState, _carryForward) {
+  const [getMessages, setMessages] = createSignal([]);
+  const [getHistory, setHistory] = createSignal([]);
+  const [getInputValue, setInputValue] = createSignal("");
+  const [getIsLoading, setIsLoading] = createSignal(false);
+  const [getIsExpanded, setIsExpanded] = createSignal(false);
+  const [getError, setError] = createSignal(null);
+  const hasMessages = createMemo(() => getMessages().length > 0);
+  const hasError = createMemo(() => getError() !== null);
+  const lastUserMessage = createMemo(() => {
+    const msgs = getMessages();
+    for (let i = msgs.length - 1; i >= 0; i--) {
+      if (msgs[i].role === "user")
+        return msgs[i].content;
+    }
+    return "";
+  });
+  const lastAssistantMessage = createMemo(() => {
+    const msgs = getMessages();
+    for (let i = msgs.length - 1; i >= 0; i--) {
+      if (msgs[i].role === "assistant")
+        return msgs[i].content;
+    }
+    return "";
+  });
+  const getAutomation = () => window.__jay?.automation || null;
+  function getToolsAndState() {
+    const automation = getAutomation();
+    if (!automation) {
+      return { toolDefinitions: [], pageState: {} };
+    }
+    return {
+      toolDefinitions: buildSerializedTools(automation),
+      pageState: automation.getPageState().viewState
+    };
+  }
+  async function handleToolCalls(output) {
+    while (output.type === "tool-calls") {
+      setHistory(output.history);
+      const automation = getAutomation();
+      if (!automation) {
+        setError("AutomationAPI not available");
+        return;
+      }
+      const results = output.calls.filter((c) => c.category === "page-automation").map((call) => executePageAutomationTool(automation, call));
+      const { toolDefinitions, pageState } = getToolsAndState();
+      const nextOutput = await callSubmitToolResults({
+        results,
+        history: output.history,
+        toolDefinitions,
+        pageState
+      });
+      output = nextOutput;
+    }
+    const finalOutput = output;
+    if (finalOutput.type === "response") {
+      setHistory(finalOutput.history);
+      setMessages((msgs) => [
+        ...msgs,
+        {
+          index: msgs.length,
+          role: "assistant",
+          content: finalOutput.message
+        }
+      ]);
+    }
+  }
+  async function sendMessage() {
+    const message = getInputValue().trim();
+    if (!message || getIsLoading())
+      return;
+    setError(null);
+    setIsLoading(true);
+    setInputValue("");
+    setMessages((msgs) => [...msgs, { index: msgs.length, role: "user", content: message }]);
+    try {
+      const { toolDefinitions, pageState } = getToolsAndState();
+      const output = await callSendMessage({
+        message,
+        history: getHistory(),
+        toolDefinitions,
+        pageState
+      });
+      await handleToolCalls(output);
+    } catch (error) {
+      setError(error.message || "Failed to send message");
+    } finally {
+      setIsLoading(false);
+    }
+  }
+  refs.sendMessage.onclick(sendMessage);
+  refs.toggleExpand.onclick(() => {
+    setIsExpanded((v) => !v);
+  });
+  refs.messageInput.oninput((jayEvent) => {
+    setInputValue(jayEvent.event.target.value);
+  });
+  refs.messageInput.onkeydown((jayEvent) => {
+    if (jayEvent.event.key === "Enter" && !jayEvent.event.shiftKey) {
+      jayEvent.event.preventDefault();
+      sendMessage();
+    }
+  });
+  return {
+    render: () => ({
+      messages: () => getMessages().map((m) => ({
+        index: m.index,
+        role: m.role,
+        content: m.content
+      })),
+      lastUserMessage,
+      lastAssistantMessage,
+      messageInput: getInputValue,
+      isLoading: getIsLoading,
+      isExpanded: getIsExpanded,
+      hasError,
+      hasMessages,
+      errorMessage: () => getError() || ""
+    })
+  };
+}
+const geminiChat = makeJayStackComponent().withProps().withInteractive(GeminiChatInteractive);
+export {
+  GEMINI_SERVICE,
+  geminiChat,
+  init
+};

package/dist/index.d.ts

@@ -0,0 +1,244 @@
+import * as _jay_framework_fullstack_component from '@jay-framework/fullstack-component';
+import { Signals } from '@jay-framework/fullstack-component';
+import * as _google_genai from '@google/genai';
+import { PluginSetupContext, PluginSetupResult, ActionMetadata } from '@jay-framework/stack-server-runtime';
+import * as _jay_framework_component from '@jay-framework/component';
+import { HTMLElementProxy } from '@jay-framework/runtime';
+
+/**
+ * Shared type definitions for the Gemini agent plugin.
+ */
+interface GeminiMessage {
+    role: 'user' | 'model';
+    parts: GeminiPart[];
+}
+type GeminiPart = GeminiTextPart | GeminiFunctionCallPart | GeminiFunctionResponsePart;
+interface GeminiTextPart {
+    text: string;
+}
+interface GeminiFunctionCallPart {
+    functionCall: {
+        name: string;
+        args: Record<string, unknown>;
+    };
+}
+interface GeminiFunctionResponsePart {
+    functionResponse: {
+        name: string;
+        response: Record<string, unknown>;
+    };
+}
+interface SerializedToolDef {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, any>;
+        required?: string[];
+    };
+    category: 'page-automation';
+}
+interface SendMessageInput {
+    /** User's message text */
+    message: string;
+    /** Full conversation history (Gemini format) */
+    history: GeminiMessage[];
+    /** Page automation tool definitions (serialized from client) */
+    toolDefinitions: SerializedToolDef[];
+    /** Current page state snapshot */
+    pageState: object;
+}
+interface PendingToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    category: 'page-automation' | 'server-action';
+}
+type SendMessageOutput = {
+    type: 'response';
+    message: string;
+    history: GeminiMessage[];
+} | {
+    type: 'tool-calls';
+    calls: PendingToolCall[];
+    history: GeminiMessage[];
+};
+interface SubmitToolResultsInput {
+    /** Tool execution results */
+    results: ToolCallResult[];
+    /** Full conversation history (including the tool call turn) */
+    history: GeminiMessage[];
+    /** Resend tool definitions (page state may have changed) */
+    toolDefinitions: SerializedToolDef[];
+    /** Fresh page state (may have changed after tool execution) */
+    pageState: object;
+}
+interface ToolCallResult {
+    callId: string;
+    /** JSON-stringified result */
+    result: string;
+    isError?: boolean;
+}
+type SubmitToolResultsOutput = SendMessageOutput;
+interface GeminiFunctionDeclaration {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, any>;
+        required?: string[];
+    };
+}
+interface GeminiServiceConfig {
+    apiKey: string;
+    model: string;
+    systemPrompt?: string;
+}
+
+declare class GeminiService {
+    private config;
+    private client;
+    constructor(config: GeminiServiceConfig);
+    get model(): string;
+    get systemPromptPrefix(): string | undefined;
+    generateWithTools(messages: GeminiMessage[], tools: GeminiFunctionDeclaration[], systemPrompt: string): Promise<_google_genai.GenerateContentResponse>;
+}
+
+declare const GEMINI_SERVICE: _jay_framework_fullstack_component.ServiceMarker<GeminiService>;
+declare const init: _jay_framework_fullstack_component.JayInitBuilderWithServer<{}>;
+
+/**
+ * Setup handler for gemini-agent plugin.
+ *
+ * Creates config/.gemini.yaml template if missing, validates the API key.
+ */
+
+declare function setupGeminiAgent(ctx: PluginSetupContext): Promise<PluginSetupResult>;
+
+/**
+ * Main entry point for chat messages.
+ *
+ * Receives the user message, full conversation history, tool definitions,
+ * and page state. Returns either a text response or pending tool calls.
+ */
+declare const sendMessage: _jay_framework_fullstack_component.JayAction<SendMessageInput, SendMessageOutput> & _jay_framework_fullstack_component.JayActionDefinition<SendMessageInput, SendMessageOutput, [GeminiService]>;
+/**
+ * Continue after client executes page automation tools.
+ *
+ * Receives tool execution results, the updated history, and fresh page state.
+ * Returns either a text response or more pending tool calls.
+ */
+declare const submitToolResults: _jay_framework_fullstack_component.JayAction<SubmitToolResultsInput, SendMessageOutput> & _jay_framework_fullstack_component.JayActionDefinition<SubmitToolResultsInput, SendMessageOutput, [GeminiService]>;
+
+/**
+ * Configuration for the Gemini agent plugin.
+ */
+interface GeminiAgentConfig {
+    /** Gemini API key */
+    apiKey: string;
+    /** Model name (default: gemini-2.0-flash) */
+    model: string;
+    /** Optional system prompt prefix prepended to the generated system prompt */
+    systemPrompt?: string;
+}
+
+declare enum Role {
+  user,
+  assistant
+}
+
+interface MessageOfGeminiChatViewState {
+  index: number,
+  role: Role,
+  content: string
+}
+
+interface GeminiChatViewState {
+  messages: Array<MessageOfGeminiChatViewState>,
+  lastUserMessage: string,
+  lastAssistantMessage: string,
+  messageInput: string,
+  isLoading: boolean,
+  isExpanded: boolean,
+  hasError: boolean,
+  hasMessages: boolean,
+  errorMessage: string
+}
+
+type GeminiChatSlowViewState = {};
+
+type GeminiChatFastViewState = Pick<GeminiChatViewState, 'lastUserMessage' | 'lastAssistantMessage' | 'messageInput' | 'isLoading' | 'isExpanded' | 'hasError' | 'hasMessages' | 'errorMessage'> & {
+    messages: Array<GeminiChatViewState['messages'][number]>;
+};
+
+type GeminiChatInteractiveViewState = Pick<GeminiChatViewState, 'lastUserMessage' | 'lastAssistantMessage' | 'messageInput' | 'isLoading' | 'isExpanded' | 'hasError' | 'hasMessages' | 'errorMessage'> & {
+    messages: Array<GeminiChatViewState['messages'][number]>;
+};
+
+
+interface GeminiChatRefs {
+  messageInput: HTMLElementProxy<GeminiChatViewState, HTMLInputElement>,
+  sendMessage: HTMLElementProxy<GeminiChatViewState, HTMLButtonElement>,
+  toggleExpand: HTMLElementProxy<GeminiChatViewState, HTMLButtonElement>
+}
+
+interface GeminiChatProps {
+}
+interface ChatCarryForward {
+}
+declare const geminiChat: _jay_framework_fullstack_component.JayStackComponentDefinition<GeminiChatRefs, GeminiChatSlowViewState, GeminiChatFastViewState, GeminiChatInteractiveViewState, [], [Signals<GeminiChatFastViewState>, ChatCarryForward], GeminiChatProps, {}, _jay_framework_component.JayComponentCore<GeminiChatProps, GeminiChatInteractiveViewState>>;
+
+/**
+ * Tool Bridge — converts jay-stack tool descriptors and action metadata
+ * to Gemini FunctionDeclarations.
+ *
+ * Only actions with .jay-action metadata are exposed to the AI agent.
+ * Page automation tools (from AutomationAPI) are always included.
+ */
+
+/**
+ * Converts page automation tools and server actions into Gemini function declarations.
+ *
+ * - Client tools are included directly (already have schema).
+ * - Server actions are only included if they have .jay-action metadata.
+ *   Actions without metadata are silently skipped (opt-in mechanism).
+ */
+declare function toGeminiTools(clientTools: SerializedToolDef[], serverActions: Array<{
+    actionName: string;
+    metadata: ActionMetadata;
+}>): GeminiFunctionDeclaration[];
+/**
+ * Maps a Gemini function call name back to its original action name.
+ * Reverses the `action_` prefix and `_` → `.` replacement.
+ */
+declare function resolveToolCallTarget(toolName: string, clientToolNames: Set<string>): {
+    category: 'page-automation';
+    name: string;
+} | {
+    category: 'server-action';
+    name: string;
+};
+
+/**
+ * System Prompt Builder — constructs the system prompt for Gemini.
+ *
+ * Page state and available server actions are included as context
+ * (not tools), so the LLM always knows the current state without
+ * wasting tool calls.
+ */
+interface ServerActionSummary {
+    name: string;
+    description?: string;
+}
+/**
+ * Builds the system prompt for a Gemini conversation turn.
+ *
+ * The prompt includes:
+ * 1. Custom prefix (from config) or default greeting
+ * 2. Current page state as JSON context
+ * 3. List of available server actions with descriptions
+ * 4. Instructions for tool use
+ */
+declare function buildSystemPrompt(pageState: object, serverActions: ServerActionSummary[], customPrefix?: string): string;
+
+export { GEMINI_SERVICE, type GeminiAgentConfig, type GeminiFunctionCallPart, type GeminiFunctionDeclaration, type GeminiFunctionResponsePart, type GeminiMessage, type GeminiPart, GeminiService, type GeminiServiceConfig, type GeminiTextPart, type PendingToolCall, type SendMessageInput, type SendMessageOutput, type SerializedToolDef, type ServerActionSummary, type SubmitToolResultsInput, type SubmitToolResultsOutput, type ToolCallResult, buildSystemPrompt, geminiChat, init, resolveToolCallTarget, sendMessage, setupGeminiAgent, submitToolResults, toGeminiTools };

package/dist/index.js

@@ -0,0 +1,376 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+import { createJayService, makeJayInit, makeJayAction, makeJayStackComponent, RenderPipeline } from "@jay-framework/fullstack-component";
+import { registerService, actionRegistry } from "@jay-framework/stack-server-runtime";
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "js-yaml";
+import { Type, GoogleGenAI } from "@google/genai";
+const CONFIG_FILE_NAME$1 = ".gemini.yaml";
+const DEFAULT_MODEL = "gemini-2.0-flash";
+function loadConfig() {
+  const configPath = path.join(process.cwd(), "config", CONFIG_FILE_NAME$1);
+  if (!fs.existsSync(configPath)) {
+    throw new Error(
+      `Gemini config file not found at: ${configPath}
+Run "jay-stack setup gemini-agent" to create it.`
+    );
+  }
+  const fileContents = fs.readFileSync(configPath, "utf8");
+  const config = yaml.load(fileContents);
+  if (!config) {
+    throw new Error("Gemini config file is empty or invalid");
+  }
+  if (config.apiKey === void 0 || config.apiKey === null) {
+    throw new Error('Config validation failed: "apiKey" is required in .gemini.yaml');
+  }
+  if (typeof config.apiKey !== "string" || config.apiKey.trim() === "") {
+    throw new Error('Config validation failed: "apiKey" must be a non-empty string');
+  }
+  if (config.apiKey.startsWith("<")) {
+    throw new Error(
+      'Config validation failed: "apiKey" still has placeholder value. Replace it with your Gemini API key.'
+    );
+  }
+  return {
+    apiKey: config.apiKey,
+    model: config.model || DEFAULT_MODEL,
+    systemPrompt: config.systemPrompt || void 0
+  };
+}
+const TYPE_MAP = {
+  object: Type.OBJECT,
+  string: Type.STRING,
+  number: Type.NUMBER,
+  integer: Type.INTEGER,
+  boolean: Type.BOOLEAN,
+  array: Type.ARRAY
+};
+function toGeminiSchema(schema) {
+  const result = {};
+  if (schema.type) {
+    result.type = TYPE_MAP[schema.type] || Type.STRING;
+  }
+  if (schema.description) {
+    result.description = schema.description;
+  }
+  if (schema.enum) {
+    result.enum = schema.enum;
+  }
+  if (schema.items) {
+    result.items = toGeminiSchema(schema.items);
+  }
+  if (schema.properties) {
+    result.properties = {};
+    for (const [key, value] of Object.entries(schema.properties)) {
+      result.properties[key] = toGeminiSchema(value);
+    }
+  }
+  if (schema.required) {
+    result.required = schema.required;
+  }
+  return result;
+}
+function toSdkDeclaration(decl) {
+  return {
+    name: decl.name,
+    description: decl.description,
+    parameters: toGeminiSchema(decl.parameters)
+  };
+}
+class GeminiService {
+  constructor(config) {
+    __publicField(this, "client");
+    this.config = config;
+    this.client = new GoogleGenAI({ apiKey: config.apiKey });
+  }
+  get model() {
+    return this.config.model;
+  }
+  get systemPromptPrefix() {
+    return this.config.systemPrompt;
+  }
+  async generateWithTools(messages, tools, systemPrompt) {
+    const sdkDeclarations = tools.map(toSdkDeclaration);
+    const response = await this.client.models.generateContent({
+      model: this.config.model,
+      contents: messages,
+      config: {
+        systemInstruction: systemPrompt,
+        tools: sdkDeclarations.length > 0 ? [{ functionDeclarations: sdkDeclarations }] : void 0
+      }
+    });
+    return response;
+  }
+}
+const GEMINI_SERVICE = createJayService("GeminiService");
+const init = makeJayInit().withServer(() => {
+  const config = loadConfig();
+  const service = new GeminiService({
+    apiKey: config.apiKey,
+    model: config.model,
+    systemPrompt: config.systemPrompt
+  });
+  registerService(GEMINI_SERVICE, service);
+  console.log(`[gemini-agent] Initialized (model: ${config.model})`);
+  return {};
+});
+const CONFIG_FILE_NAME = ".gemini.yaml";
+const CONFIG_TEMPLATE = `# Gemini Agent Configuration
+#
+# This file contains credentials for the Gemini AI agent plugin.
+# Get your API key from: https://aistudio.google.com/apikey
+#
+# IMPORTANT: This file contains secrets. Add config/.gemini.yaml to .gitignore.
+
+# Required: Your Gemini API key
+apiKey: "<your-gemini-api-key>"
+
+# Optional: Model name (default: gemini-2.0-flash)
+# model: gemini-2.0-flash
+
+# Optional: Custom system prompt prefix (prepended to the generated system prompt)
+# systemPrompt: "You are a helpful assistant for this web application."
+`;
+async function setupGeminiAgent(ctx) {
+  const configPath = path.join(ctx.configDir, CONFIG_FILE_NAME);
+  if (!fs.existsSync(configPath)) {
+    if (!fs.existsSync(ctx.configDir)) {
+      fs.mkdirSync(ctx.configDir, { recursive: true });
+    }
+    fs.writeFileSync(configPath, CONFIG_TEMPLATE, "utf-8");
+    return {
+      status: "needs-config",
+      configCreated: [`config/${CONFIG_FILE_NAME}`],
+      message: "Fill in your Gemini API key and re-run: jay-stack setup gemini-agent"
+    };
+  }
+  try {
+    const configContent = fs.readFileSync(configPath, "utf-8");
+    const config = yaml.load(configContent);
+    if (!config) {
+      return {
+        status: "error",
+        message: `Config file is empty: config/${CONFIG_FILE_NAME}`
+      };
+    }
+    const apiKey = config.apiKey || "";
+    const hasPlaceholder = apiKey.startsWith("<");
+    const isEmpty = !apiKey;
+    if (hasPlaceholder || isEmpty) {
+      return {
+        status: "needs-config",
+        message: `Config has placeholder value. Set your Gemini API key in config/${CONFIG_FILE_NAME}`
+      };
+    }
+    if (ctx.initError) {
+      return {
+        status: "error",
+        message: `Gemini initialization failed: ${ctx.initError.message}`
+      };
+    }
+    return {
+      status: "configured",
+      message: `Gemini agent configured (model: ${config.model || "gemini-2.0-flash"})`
+    };
+  } catch (error) {
+    return {
+      status: "error",
+      message: `Failed to read config: ${error.message}`
+    };
+  }
+}
+function toGeminiTools(clientTools, serverActions) {
+  const tools = [];
+  for (const tool of clientTools) {
+    tools.push({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.inputSchema
+    });
+  }
+  for (const { actionName, metadata } of serverActions) {
+    tools.push({
+      name: `action_${actionName.replace(/\./g, "_")}`,
+      description: metadata.description,
+      parameters: metadata.inputSchema
+    });
+  }
+  return tools;
+}
+function resolveToolCallTarget(toolName, clientToolNames) {
+  if (clientToolNames.has(toolName)) {
+    return { category: "page-automation", name: toolName };
+  }
+  if (toolName.startsWith("action_")) {
+    const actionName = toolName.slice("action_".length).replace(/_/g, ".");
+    return { category: "server-action", name: actionName };
+  }
+  return { category: "page-automation", name: toolName };
+}
+function buildSystemPrompt(pageState, serverActions, customPrefix) {
+  const parts = [
+    customPrefix || "You are a helpful assistant for this web application.",
+    "",
+    "## Current Page State",
+    JSON.stringify(pageState, null, 2),
+    ""
+  ];
+  if (serverActions.length > 0) {
+    parts.push("## Available Server Actions");
+    for (const action of serverActions) {
+      parts.push(`- ${action.name}${action.description ? `: ${action.description}` : ""}`);
+    }
+    parts.push("");
+  }
+  parts.push(
+    "Use the provided tools to interact with the page and call server actions.",
+    "After using tools, describe what you did to the user.",
+    "The page state above is refreshed each turn — use it to understand what the user sees."
+  );
+  return parts.join("\n");
+}
+async function processGeminiTurn(service, history, tools, systemPrompt, clientToolNames) {
+  const response = await service.generateWithTools(history, tools, systemPrompt);
+  const candidate = response.candidates?.[0];
+  if (!candidate?.content?.parts) {
+    return {
+      type: "response",
+      message: "I apologize, but I was unable to generate a response.",
+      history
+    };
+  }
+  const parts = candidate.content.parts;
+  const functionCalls = parts.filter(
+    (p) => p.functionCall != null
+  );
+  const responseParts = candidate.content.parts;
+  if (functionCalls.length === 0) {
+    const textParts = parts.filter((p) => p.text != null);
+    const message = textParts.map((p) => p.text).join("");
+    const updatedHistory2 = [
+      ...history,
+      { role: "model", parts: responseParts }
+    ];
+    return {
+      type: "response",
+      message,
+      history: updatedHistory2
+    };
+  }
+  const updatedHistory = [...history, { role: "model", parts: responseParts }];
+  const pendingClientCalls = [];
+  const serverCallResults = [];
+  for (const fc of functionCalls) {
+    const target = resolveToolCallTarget(fc.functionCall.name, clientToolNames);
+    if (target.category === "server-action") {
+      const result = await actionRegistry.execute(target.name, fc.functionCall.args);
+      serverCallResults.push({
+        functionResponse: {
+          name: fc.functionCall.name,
+          response: result.success ? { result: result.data } : { error: result.error?.message || "Unknown error" }
+        }
+      });
+    } else {
+      pendingClientCalls.push({
+        id: fc.functionCall.name,
+        name: fc.functionCall.name,
+        args: fc.functionCall.args || {},
+        category: "page-automation"
+      });
+    }
+  }
+  if (pendingClientCalls.length > 0) {
+    [
+      ...pendingClientCalls,
+      // Server actions already executed — include as completed calls
+      ...serverCallResults.map((r) => ({
+        id: r.functionResponse.name,
+        name: r.functionResponse.name,
+        args: {},
+        category: "server-action"
+      }))
+    ];
+    return {
+      type: "tool-calls",
+      calls: pendingClientCalls,
+      history: updatedHistory
+    };
+  }
+  const historyWithResults = [
+    ...updatedHistory,
+    { role: "user", parts: serverCallResults }
+  ];
+  return processGeminiTurn(service, historyWithResults, tools, systemPrompt, clientToolNames);
+}
+async function handleConversation(service, history, toolDefinitions, pageState) {
+  const serverActions = actionRegistry.getActionsWithMetadata();
+  const tools = toGeminiTools(toolDefinitions, serverActions);
+  const serverActionSummaries = serverActions.map((a) => ({
+    name: a.actionName,
+    description: a.metadata.description
+  }));
+  const systemPrompt = buildSystemPrompt(
+    pageState,
+    serverActionSummaries,
+    service.systemPromptPrefix
+  );
+  const clientToolNames = new Set(toolDefinitions.map((t) => t.name));
+  return processGeminiTurn(service, history, tools, systemPrompt, clientToolNames);
+}
+const sendMessage = makeJayAction("geminiAgent.sendMessage").withServices(GEMINI_SERVICE).withHandler(async (input, service) => {
+  const { message, history, toolDefinitions, pageState } = input;
+  const updatedHistory = [
+    ...history,
+    { role: "user", parts: [{ text: message }] }
+  ];
+  return handleConversation(service, updatedHistory, toolDefinitions, pageState);
+});
+const submitToolResults = makeJayAction("geminiAgent.submitToolResults").withServices(GEMINI_SERVICE).withHandler(async (input, service) => {
+  const { results, history, toolDefinitions, pageState } = input;
+  const functionResponses = results.map((r) => ({
+    functionResponse: {
+      name: r.callId,
+      response: r.isError ? { error: r.result } : JSON.parse(r.result)
+    }
+  }));
+  const updatedHistory = [
+    ...history,
+    { role: "user", parts: functionResponses }
+  ];
+  return handleConversation(service, updatedHistory, toolDefinitions, pageState);
+});
+async function fastRender() {
+  const Pipeline = RenderPipeline.for();
+  return Pipeline.ok({}).toPhaseOutput(() => ({
+    viewState: {
+      messages: [],
+      lastUserMessage: "",
+      lastAssistantMessage: "",
+      messageInput: "",
+      isLoading: false,
+      isExpanded: false,
+      hasError: false,
+      hasMessages: false,
+      errorMessage: ""
+    },
+    carryForward: {}
+  }));
+}
+const geminiChat = makeJayStackComponent().withProps().withFastRender(fastRender);
+export {
+  GEMINI_SERVICE,
+  GeminiService,
+  buildSystemPrompt,
+  geminiChat,
+  init,
+  resolveToolCallTarget,
+  sendMessage,
+  setupGeminiAgent,
+  submitToolResults,
+  toGeminiTools
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@jay-framework/gemini-agent-plugin",
+  "version": "0.12.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Gemini AI agent plugin for jay-stack — embedded chat agent with page automation and server action calling",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./client": "./dist/index.client.js",
+    "./gemini-chat.jay-contract": "./dist/contracts/gemini-chat.jay-contract",
+    "./send-message.jay-action": "./dist/actions/send-message.jay-action",
+    "./submit-tool-results.jay-action": "./dist/actions/submit-tool-results.jay-action",
+    "./plugin.yaml": "./plugin.yaml"
+  },
+  "files": [
+    "dist",
+    "plugin.yaml"
+  ],
+  "scripts": {
+    "build": "npm run definitions && npm run build:client && npm run build:server && npm run build:copy-contract && npm run build:types",
+    "build:client": "vite build",
+    "build:server": "vite build --ssr",
+    "build:copy-contract": "mkdir -p dist/contracts && cp lib/contracts/*.jay-contract* dist/contracts/ && mkdir -p dist/actions && cp lib/actions/*.jay-action dist/actions/",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "definitions": "jay-cli definitions lib",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run build:check-types && npm run test",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@google/genai": "^0.14.0",
+    "@jay-framework/component": "^0.12.0",
+    "@jay-framework/fullstack-component": "^0.12.0",
+    "@jay-framework/runtime": "^0.12.0",
+    "@jay-framework/runtime-automation": "^0.12.0",
+    "@jay-framework/stack-client-runtime": "^0.12.0",
+    "@jay-framework/stack-server-runtime": "^0.12.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@jay-framework/compiler-jay-stack": "^0.12.0",
+    "@jay-framework/dev-environment": "^0.12.0",
+    "@jay-framework/jay-cli": "^0.12.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.15.21",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.1"
+  }
+}

package/plugin.yaml

@@ -0,0 +1,15 @@
+name: gemini-agent
+global: true
+contracts:
+  - name: gemini-chat
+    contract: gemini-chat.jay-contract
+    component: geminiChat
+    description: AI chat agent powered by Gemini with page automation capabilities
+actions:
+  - name: sendMessage
+    action: send-message.jay-action
+  - name: submitToolResults
+    action: submit-tool-results.jay-action
+setup:
+  handler: setupGeminiAgent
+  description: Configure Gemini API key