@jay-framework/gemini-agent-plugin 0.13.0 → 0.14.0

package/dist/index.client.js

@@ -1,43 +1,115 @@
 import { createJayService, makeJayInit, makeJayStackComponent } from "@jay-framework/fullstack-component";
-import { createSignal, createMemo } from "@jay-framework/component";
+import { createSignal, createMemo, createDerivedArray } 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) {
+var Role = /* @__PURE__ */ ((Role2) => {
+  Role2[Role2["user"] = 0] = "user";
+  Role2[Role2["assistant"] = 1] = "assistant";
+  return Role2;
+})(Role || {});
+const MAX_ARRAY_ITEMS = 3;
+const MAX_STRING_LENGTH = 200;
+function compactPageState(value) {
+  if (value === null || value === void 0)
+    return value;
+  if (typeof value === "string") {
+    if (value.length > MAX_STRING_LENGTH) {
+      return value.slice(0, MAX_STRING_LENGTH) + "...";
+    }
+    return value;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > MAX_ARRAY_ITEMS) {
+      const truncated = value.slice(0, MAX_ARRAY_ITEMS).map(compactPageState);
+      truncated.push(`... (${value.length} total)`);
+      return truncated;
+    }
+    return value.map(compactPageState);
+  }
+  if (typeof value === "object") {
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = compactPageState(v);
+    }
+    return result;
+  }
+  return value;
+}
+const sendMessage = createActionCaller("geminiAgent.sendMessage", "POST");
+const submitToolResults = createActionCaller("geminiAgent.submitToolResults", "POST");
+const getToolDescriptions = createActionCaller("geminiAgent.getToolDescriptions", "GET");
+const FILLABLE_TYPES = /* @__PURE__ */ new Set(["HTMLInputElement", "HTMLTextAreaElement", "HTMLSelectElement"]);
+function isCheckable(element) {
+  return element instanceof HTMLInputElement && (element.type === "checkbox" || element.type === "radio");
+}
+function getSelectOptions(element) {
+  if (!(element instanceof HTMLSelectElement))
+    return void 0;
+  return Array.from(element.options).map((opt) => opt.value);
+}
+function setElementValue(element, value) {
+  if (isCheckable(element)) {
+    element.checked = value === "true";
+  } else {
+    element.value = value;
+  }
+}
+function getValueEventTypes(registeredEvents) {
+  const result = [];
+  if (registeredEvents.includes("input"))
+    result.push("input");
+  if (registeredEvents.includes("change"))
+    result.push("change");
+  if (result.length > 0)
+    return result;
+  return registeredEvents.length > 0 ? [registeredEvents[0]] : ["input"];
+}
+const CHAT_WIDGET_REFS = /* @__PURE__ */ new Set(["messageInput", "sendMessage", "toggleExpand"]);
+function buildSerializedTools(automation, descriptionMap) {
   const { interactions } = automation.getPageState();
   const tools = [];
   for (const group of interactions) {
+    if (CHAT_WIDGET_REFS.has(group.refName))
+      continue;
     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 isFillable = FILLABLE_TYPES.has(elementType);
+    const isSelect = elementType === "HTMLSelectElement";
+    const checkable = isCheckable(sample.element);
     const isForEach = group.items.length > 1 || sample.coordinate.length > 1;
-    const prefix = isCheckbox ? "toggle" : isFillable ? "fill" : "click";
+    const prefix = checkable ? "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 description = descriptionMap.get(group.refName) || group.description || `${checkable ? "Toggle" : isFillable ? "Fill" : "Click"} ${humanName}${isForEach ? " for a specific item" : ""}`;
     const properties = {};
     const required = [];
     if (isForEach) {
+      const coordStrings = group.items.map((i) => i.coordinate.join("/"));
       properties.coordinate = {
         type: "string",
-        description: `Item coordinate (e.g. "${sample.coordinate.join("/")}")`
+        description: "Item coordinate",
+        enum: coordStrings
       };
       required.push("coordinate");
     }
-    if (isFillable && !isCheckbox) {
-      properties.value = {
-        type: "string",
-        description: `Value to set in ${humanName}`
-      };
+    if (isFillable) {
+      if (checkable) {
+        properties.value = {
+          type: "string",
+          description: "Checked state",
+          enum: ["true", "false"]
+        };
+      } else {
+        const selectOptions = isSelect ? getSelectOptions(sample.element) : void 0;
+        properties.value = {
+          type: "string",
+          description: isSelect ? "Value to select" : `Value to set in ${humanName}`,
+          ...selectOptions ? { enum: selectOptions } : {}
+        };
+      }
       required.push("value");
     }
     tools.push({
@@ -77,7 +149,6 @@ function executePageAutomationTool(automation, call) {
     }
     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) {
@@ -87,23 +158,21 @@ function executePageAutomationTool(automation, call) {
         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);
+    if (prefix === "fill" || prefix === "toggle") {
+      setElementValue(item.element, String(args.value));
+      for (const evt of getValueEventTypes(item.events)) {
+        item.element.dispatchEvent(new Event(evt, { bubbles: true }));
       }
-      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 })
+      result: JSON.stringify({
+        success: true,
+        pageState: compactPageState(newState.viewState)
+      })
     };
   } catch (error) {
     return {
@@ -121,11 +190,12 @@ function GeminiChatInteractive(_props, refs, fastViewState, _carryForward) {
   const [getIsExpanded, setIsExpanded] = createSignal(false);
   const [getError, setError] = createSignal(null);
   const hasMessages = createMemo(() => getMessages().length > 0);
+  const displayMessages = createDerivedArray(getMessages, (item) => item());
   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")
+      if (msgs[i].role === Role.user)
         return msgs[i].content;
     }
     return "";
@@ -133,39 +203,49 @@ function GeminiChatInteractive(_props, refs, fastViewState, _carryForward) {
   const lastAssistantMessage = createMemo(() => {
     const msgs = getMessages();
     for (let i = msgs.length - 1; i >= 0; i--) {
-      if (msgs[i].role === "assistant")
+      if (msgs[i].role === Role.assistant)
         return msgs[i].content;
     }
     return "";
   });
-  const getAutomation = () => window.__jay?.automation || null;
+  let automation = window.__jay?.automation || null;
+  if (!automation) {
+    window.addEventListener("jay:automation-ready", () => {
+      automation = window.__jay?.automation || null;
+    }, { once: true });
+  }
+  const getAutomation = () => automation;
+  let toolDescriptionMap = /* @__PURE__ */ new Map();
+  getToolDescriptions(void 0).then((descriptions) => {
+    toolDescriptionMap = new Map(descriptions.map((d) => [d.refName, d.description]));
+  }).catch(() => {
+  });
   function getToolsAndState() {
-    const automation = getAutomation();
-    if (!automation) {
+    const automation2 = getAutomation();
+    if (!automation2) {
       return { toolDefinitions: [], pageState: {} };
     }
     return {
-      toolDefinitions: buildSerializedTools(automation),
-      pageState: automation.getPageState().viewState
+      toolDefinitions: buildSerializedTools(automation2, toolDescriptionMap),
+      pageState: automation2.getPageState().viewState
     };
   }
   async function handleToolCalls(output) {
     while (output.type === "tool-calls") {
       setHistory(output.history);
-      const automation = getAutomation();
-      if (!automation) {
+      const automation2 = getAutomation();
+      if (!automation2) {
         setError("AutomationAPI not available");
         return;
       }
-      const results = output.calls.filter((c) => c.category === "page-automation").map((call) => executePageAutomationTool(automation, call));
+      const results = output.calls.filter((c) => c.category === "page-automation").map((call) => executePageAutomationTool(automation2, call));
       const { toolDefinitions, pageState } = getToolsAndState();
-      const nextOutput = await callSubmitToolResults({
+      output = await submitToolResults({
         results,
         history: output.history,
         toolDefinitions,
         pageState
       });
-      output = nextOutput;
     }
     const finalOutput = output;
     if (finalOutput.type === "response") {
@@ -174,23 +254,23 @@ function GeminiChatInteractive(_props, refs, fastViewState, _carryForward) {
         ...msgs,
         {
           index: msgs.length,
-          role: "assistant",
+          role: Role.assistant,
           content: finalOutput.message
         }
       ]);
     }
   }
-  async function sendMessage() {
+  async function sendMessage$1() {
     const message = getInputValue().trim();
     if (!message || getIsLoading())
       return;
     setError(null);
     setIsLoading(true);
     setInputValue("");
-    setMessages((msgs) => [...msgs, { index: msgs.length, role: "user", content: message }]);
+    setMessages((msgs) => [...msgs, { index: msgs.length, role: Role.user, content: message }]);
     try {
       const { toolDefinitions, pageState } = getToolsAndState();
-      const output = await callSendMessage({
+      const output = await sendMessage({
         message,
         history: getHistory(),
         toolDefinitions,
@@ -203,7 +283,7 @@ function GeminiChatInteractive(_props, refs, fastViewState, _carryForward) {
       setIsLoading(false);
     }
   }
-  refs.sendMessage.onclick(sendMessage);
+  refs.sendMessage.onclick(sendMessage$1);
   refs.toggleExpand.onclick(() => {
     setIsExpanded((v) => !v);
   });
@@ -213,16 +293,12 @@ function GeminiChatInteractive(_props, refs, fastViewState, _carryForward) {
   refs.messageInput.onkeydown((jayEvent) => {
     if (jayEvent.event.key === "Enter" && !jayEvent.event.shiftKey) {
       jayEvent.event.preventDefault();
-      sendMessage();
+      sendMessage$1();
     }
   });
   return {
     render: () => ({
-      messages: () => getMessages().map((m) => ({
-        index: m.index,
-        role: m.role,
-        content: m.content
-      })),
+      messages: displayMessages,
       lastUserMessage,
       lastAssistantMessage,
       messageInput: getInputValue,

package/dist/index.d.ts

@@ -115,6 +115,19 @@ declare const init: _jay_framework_fullstack_component.JayInitBuilderWithServer<
 
 declare function setupGeminiAgent(ctx: PluginSetupContext): Promise<PluginSetupResult>;
 
+/**
+ * Tool Description Loader — reads .jay-contract files and extracts
+ * descriptions for interactive tags.
+ *
+ * Descriptions are loaded from contract YAML at runtime (not embedded
+ * in the HTML/JS bundle) so the cost is only paid when the AI agent
+ * is present.
+ */
+interface ToolDescription {
+    refName: string;
+    description: string;
+}
+
 /**
  * Main entry point for chat messages.
  *
@@ -129,6 +142,14 @@ declare const sendMessage: _jay_framework_fullstack_component.JayAction<SendMess
  * 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]>;
+/**
+ * Returns tool descriptions extracted from .jay-contract files.
+ *
+ * Internal use only — called once by the client component at init.
+ * Not exposed to the LLM (filtered by geminiAgent.* prefix).
+ * Results are cached server-side after the first call.
+ */
+declare const getToolDescriptions: _jay_framework_fullstack_component.JayAction<unknown, ToolDescription[]> & _jay_framework_fullstack_component.JayActionDefinition<unknown, ToolDescription[], []>;
 
 /**
  * Configuration for the Gemini agent plugin.
@@ -192,21 +213,52 @@ declare const geminiChat: _jay_framework_fullstack_component.JayStackComponentDe
  * 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.
+ * Slim declarations (name + description, empty params) are sent so
+ * Gemini knows the exact tool names. When the LLM calls a tool that
+ * hasn't been discovered via get_tool_details, it gets an error
+ * response telling it to discover first. After discovery, the full
+ * declaration replaces the slim one for subsequent calls.
  */
 
 /**
- * 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).
+ * The `get_page_state` meta-tool declaration.
+ * Returns the full untruncated page state on demand. The system prompt
+ * includes a compact (truncated) version; this tool provides the full data
+ * when the LLM needs it (e.g., listing all products).
+ */
+declare const PAGE_STATE_TOOL: GeminiFunctionDeclaration;
+/**
+ * The `get_tool_details` meta-tool declaration.
+ * Added to every Gemini call so the LLM can discover full parameter
+ * schemas on demand instead of receiving them all upfront.
+ */
+declare const DISCOVERY_TOOL: GeminiFunctionDeclaration;
+/**
+ * Converts page automation tools and server actions into full Gemini
+ * function declarations (with complete parameter schemas).
  */
 declare function toGeminiTools(clientTools: SerializedToolDef[], serverActions: Array<{
     actionName: string;
     metadata: ActionMetadata;
 }>): GeminiFunctionDeclaration[];
+/**
+ * Converts page automation tools and server actions into slim Gemini
+ * function declarations — name + description only, empty parameters.
+ * Ensures Gemini uses correct tool names. The LLM must call
+ * get_tool_details before using any tool.
+ */
+declare function toSlimGeminiTools(clientTools: SerializedToolDef[], serverActions: Array<{
+    actionName: string;
+    metadata: ActionMetadata;
+}>): GeminiFunctionDeclaration[];
+/**
+ * Builds a compact text summary of all available tools for the system prompt.
+ * Lists tool names and descriptions, with param names where applicable.
+ */
+declare function buildToolSummary(clientTools: SerializedToolDef[], serverActions: Array<{
+    actionName: string;
+    metadata: ActionMetadata;
+}>): string;
 /**
  * Maps a Gemini function call name back to its original action name.
  * Reverses the `action_` prefix and `_` → `.` replacement.
@@ -222,23 +274,24 @@ declare function resolveToolCallTarget(toolName: string, clientToolNames: Set<st
 /**
  * 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.
+ * Page state is compacted (no pretty-printing, truncated arrays/strings)
+ * to reduce token usage. Tool summaries replace per-tool schema details.
  */
-interface ServerActionSummary {
-    name: string;
-    description?: string;
-}
+/**
+ * Recursively compacts a page state object to reduce token usage:
+ * - Arrays longer than 3 items are truncated with a count suffix
+ * - Strings longer than 200 chars are truncated with ellipsis
+ */
+declare function compactPageState(value: unknown): unknown;
 /**
  * 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
+ * 2. Current page state as compact JSON context
+ * 3. Tool summary list
+ * 4. Instructions for tool use and discovery
  */
-declare function buildSystemPrompt(pageState: object, serverActions: ServerActionSummary[], customPrefix?: string): string;
+declare function buildSystemPrompt(pageState: object, toolSummary: string, 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 };
+export { DISCOVERY_TOOL, GEMINI_SERVICE, type GeminiAgentConfig, type GeminiFunctionCallPart, type GeminiFunctionDeclaration, type GeminiFunctionResponsePart, type GeminiMessage, type GeminiPart, GeminiService, type GeminiServiceConfig, type GeminiTextPart, PAGE_STATE_TOOL, type PendingToolCall, type SendMessageInput, type SendMessageOutput, type SerializedToolDef, type SubmitToolResultsInput, type SubmitToolResultsOutput, type ToolCallResult, buildSystemPrompt, buildToolSummary, compactPageState, geminiChat, getToolDescriptions, init, resolveToolCallTarget, sendMessage, setupGeminiAgent, submitToolResults, toGeminiTools, toSlimGeminiTools };

package/dist/index.js

@@ -10,6 +10,8 @@ import * as fs from "fs";
 import * as path from "path";
 import * as yaml from "js-yaml";
 import { Type, GoogleGenAI } from "@google/genai";
+import * as fs$1 from "node:fs";
+import * as path$1 from "node:path";
 const CONFIG_FILE_NAME$1 = ".gemini.yaml";
 const DEFAULT_MODEL = "gemini-2.0-flash";
 function loadConfig() {
@@ -184,6 +186,39 @@ async function setupGeminiAgent(ctx) {
     };
   }
 }
+const defaultLogger = {
+  important: (msg, ...args) => console.log(msg, ...args),
+  info: (msg, ...args) => console.log(msg, ...args),
+  warn: (msg, ...args) => console.warn(msg, ...args),
+  error: (msg, ...args) => console.error(msg, ...args)
+};
+let currentLogger = defaultLogger;
+function getLogger() {
+  return currentLogger;
+}
+const PAGE_STATE_TOOL = {
+  name: "get_page_state",
+  description: "Get the full current page state. Use when the compact state in context is insufficient (e.g., to see all items in a truncated list).",
+  parameters: {
+    type: "object",
+    properties: {}
+  }
+};
+const DISCOVERY_TOOL = {
+  name: "get_tool_details",
+  description: "Get full parameter schemas for tools. Call before using tools that need coordinates or specific values.",
+  parameters: {
+    type: "object",
+    properties: {
+      tool_names: {
+        type: "array",
+        items: { type: "string" },
+        description: "Names of tools to get details for"
+      }
+    },
+    required: ["tool_names"]
+  }
+};
 function toGeminiTools(clientTools, serverActions) {
   const tools = [];
   for (const tool of clientTools) {
@@ -202,6 +237,39 @@ function toGeminiTools(clientTools, serverActions) {
   }
   return tools;
 }
+function toSlimGeminiTools(clientTools, serverActions) {
+  const tools = [];
+  for (const tool of clientTools) {
+    tools.push({
+      name: tool.name,
+      description: tool.description,
+      parameters: { type: "object", properties: {} }
+    });
+  }
+  for (const { actionName, metadata } of serverActions) {
+    tools.push({
+      name: `action_${actionName.replace(/\./g, "_")}`,
+      description: metadata.description,
+      parameters: { type: "object", properties: {} }
+    });
+  }
+  return tools;
+}
+function buildToolSummary(clientTools, serverActions) {
+  const lines = [];
+  for (const tool of clientTools) {
+    const paramNames = Object.keys(tool.inputSchema.properties || {});
+    const paramSuffix = paramNames.length > 0 ? ` (params: ${paramNames.join(", ")})` : "";
+    lines.push(`- ${tool.name}: ${tool.description}${paramSuffix}`);
+  }
+  for (const { actionName, metadata } of serverActions) {
+    const toolName = `action_${actionName.replace(/\./g, "_")}`;
+    const paramNames = Object.keys(metadata.inputSchema?.properties || {});
+    const paramSuffix = paramNames.length > 0 ? ` (params: ${paramNames.join(", ")})` : "";
+    lines.push(`- ${toolName}: ${metadata.description}${paramSuffix}`);
+  }
+  return lines.join("\n");
+}
 function resolveToolCallTarget(toolName, clientToolNames) {
   if (clientToolNames.has(toolName)) {
     return { category: "page-automation", name: toolName };
@@ -212,32 +280,83 @@ function resolveToolCallTarget(toolName, clientToolNames) {
   }
   return { category: "page-automation", name: toolName };
 }
-function buildSystemPrompt(pageState, serverActions, customPrefix) {
+const MAX_ARRAY_ITEMS = 3;
+const MAX_STRING_LENGTH = 200;
+function compactPageState(value) {
+  if (value === null || value === void 0)
+    return value;
+  if (typeof value === "string") {
+    if (value.length > MAX_STRING_LENGTH) {
+      return value.slice(0, MAX_STRING_LENGTH) + "...";
+    }
+    return value;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > MAX_ARRAY_ITEMS) {
+      const truncated = value.slice(0, MAX_ARRAY_ITEMS).map(compactPageState);
+      truncated.push(`... (${value.length} total)`);
+      return truncated;
+    }
+    return value.map(compactPageState);
+  }
+  if (typeof value === "object") {
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = compactPageState(v);
+    }
+    return result;
+  }
+  return value;
+}
+function buildSystemPrompt(pageState, toolSummary, customPrefix) {
+  const compacted = compactPageState(pageState);
   const parts = [
     customPrefix || "You are a helpful assistant for this web application.",
     "",
     "## Current Page State",
-    JSON.stringify(pageState, null, 2),
+    JSON.stringify(compacted),
     ""
   ];
-  if (serverActions.length > 0) {
-    parts.push("## Available Server Actions");
-    for (const action of serverActions) {
-      parts.push(`- ${action.name}${action.description ? `: ${action.description}` : ""}`);
-    }
+  if (toolSummary) {
+    parts.push("## Available Tools");
+    parts.push(toolSummary);
     parts.push("");
   }
   parts.push(
-    "Use the provided tools to interact with the page and call server actions.",
+    "## Instructions",
+    "You can interact with the page using the tools listed above.",
+    "Before using any tool, call `get_tool_details` with the tool names to discover and enable them.",
+    "The page state above is a compact summary. Call `get_page_state` for the full untruncated state when needed.",
+    "",
+    "There are two kinds of tools:",
+    "- **Page tools** (click-*, fill-*, toggle-*): These change what the user sees on the page. Use these to interact with the UI.",
+    "- **Server actions** (action_*): These fetch or send data to the backend. Results are returned to YOU only — the user does NOT see them on the page. Use page tools to update the UI after server actions.",
+    "",
+    "Prefer page tools to drive the UI. Only use server actions when the page tools cannot achieve the goal.",
     "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."
+    "The page state is refreshed each turn — use it to understand what the user sees."
   );
   return parts.join("\n");
 }
-async function processGeminiTurn(service, history, tools, systemPrompt, clientToolNames) {
+function approxSize(value) {
+  return JSON.stringify(value).length;
+}
+const META_TOOL_NAMES = /* @__PURE__ */ new Set(["get_tool_details", "get_page_state"]);
+async function processGeminiTurn(service, history, tools, systemPrompt, clientToolNames, fullToolLookup, pageState, discoveredTools, turnNumber = 1) {
+  const log = getLogger();
+  const lastUserMsg = [...history].reverse().find((m) => m.role === "user" && m.parts.some((p) => p.text));
+  const userText = lastUserMsg ? lastUserMsg.parts.find((p) => p.text)?.text || "" : "";
+  const historySize = approxSize(history);
+  const toolNames = tools.map((t) => t.name);
+  log.info(
+    `[gemini-agent] Turn ${turnNumber} | user: "${userText}" | history: ${history.length} msgs (~${historySize} chars) | tools: ${toolNames.length} (${toolNames.join(", ")}) | prompt: ${systemPrompt.length} chars`
+  );
+  const startTime = Date.now();
   const response = await service.generateWithTools(history, tools, systemPrompt);
+  const duration = Date.now() - startTime;
   const candidate = response.candidates?.[0];
   if (!candidate?.content?.parts) {
+    log.info(`[gemini-agent] Turn ${turnNumber} | response: empty | ${duration}ms`);
     return {
       type: "response",
       message: "I apologize, but I was unable to generate a response.",
@@ -249,9 +368,14 @@ async function processGeminiTurn(service, history, tools, systemPrompt, clientTo
     (p) => p.functionCall != null
   );
   const responseParts = candidate.content.parts;
+  const responseSize = approxSize(responseParts);
   if (functionCalls.length === 0) {
     const textParts = parts.filter((p) => p.text != null);
     const message = textParts.map((p) => p.text).join("");
+    log.info(
+      `[gemini-agent] Turn ${turnNumber} | response: text (~${responseSize} chars) | ${duration}ms
+${JSON.stringify(responseParts, null, 2)}`
+    );
     const updatedHistory2 = [
       ...history,
       { role: "model", parts: responseParts }
@@ -262,11 +386,80 @@ async function processGeminiTurn(service, history, tools, systemPrompt, clientTo
       history: updatedHistory2
     };
   }
+  const callNames = functionCalls.map((fc) => fc.functionCall.name);
+  log.info(
+    `[gemini-agent] Turn ${turnNumber} | response: tool-calls (${callNames.join(", ")}) (~${responseSize} chars) | ${duration}ms
+${JSON.stringify(responseParts, null, 2)}`
+  );
   const updatedHistory = [...history, { role: "model", parts: responseParts }];
   const pendingClientCalls = [];
   const serverCallResults = [];
+  let expandedTools = tools;
   for (const fc of functionCalls) {
-    const target = resolveToolCallTarget(fc.functionCall.name, clientToolNames);
+    const name = fc.functionCall.name;
+    if (name === "get_page_state") {
+      serverCallResults.push({
+        functionResponse: {
+          name: "get_page_state",
+          response: pageState
+        }
+      });
+      continue;
+    }
+    if (name === "get_tool_details") {
+      const requestedNames = fc.functionCall.args?.tool_names || [];
+      const schemas = {};
+      const newFullDeclarations = [];
+      for (const toolName of requestedNames) {
+        const full = fullToolLookup.get(toolName);
+        if (full) {
+          schemas[toolName] = full.parameters;
+          discoveredTools.add(toolName);
+          if (!newFullDeclarations.some((d) => d.name === toolName)) {
+            newFullDeclarations.push(full);
+          }
+        }
+      }
+      if (newFullDeclarations.length > 0) {
+        const upgradeNames = new Set(newFullDeclarations.map((d) => d.name));
+        expandedTools = [
+          ...expandedTools.filter((t) => !upgradeNames.has(t.name)),
+          ...newFullDeclarations
+        ];
+      }
+      serverCallResults.push({
+        functionResponse: {
+          name: "get_tool_details",
+          response: schemas
+        }
+      });
+      continue;
+    }
+    if (!META_TOOL_NAMES.has(name) && !discoveredTools.has(name)) {
+      const full = fullToolLookup.get(name);
+      if (full) {
+        discoveredTools.add(name);
+        const upgradeNames = /* @__PURE__ */ new Set([name]);
+        expandedTools = [...expandedTools.filter((t) => !upgradeNames.has(t.name)), full];
+        serverCallResults.push({
+          functionResponse: {
+            name,
+            response: {
+              error: `This tool requires parameters. Here is the schema: ${JSON.stringify(full.parameters)}. Call ${name} again with the correct parameters.`
+            }
+          }
+        });
+      } else {
+        serverCallResults.push({
+          functionResponse: {
+            name,
+            response: { error: `Unknown tool '${name}'.` }
+          }
+        });
+      }
+      continue;
+    }
+    const target = resolveToolCallTarget(name, clientToolNames);
     if (target.category === "server-action") {
       const result = await actionRegistry.execute(target.name, fc.functionCall.args);
       serverCallResults.push({
@@ -285,16 +478,6 @@ async function processGeminiTurn(service, history, tools, systemPrompt, clientTo
     }
   }
   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,
@@ -305,22 +488,120 @@ async function processGeminiTurn(service, history, tools, systemPrompt, clientTo
     ...updatedHistory,
     { role: "user", parts: serverCallResults }
   ];
-  return processGeminiTurn(service, historyWithResults, tools, systemPrompt, clientToolNames);
+  return processGeminiTurn(
+    service,
+    historyWithResults,
+    expandedTools,
+    systemPrompt,
+    clientToolNames,
+    fullToolLookup,
+    pageState,
+    discoveredTools,
+    turnNumber + 1
+  );
 }
 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(
+  const serverActions = actionRegistry.getActionsWithMetadata().filter((a) => !a.actionName.startsWith("geminiAgent."));
+  const fullTools = toGeminiTools(toolDefinitions, serverActions);
+  const fullToolLookup = /* @__PURE__ */ new Map();
+  for (const tool of fullTools) {
+    fullToolLookup.set(tool.name, tool);
+  }
+  const slimTools = toSlimGeminiTools(toolDefinitions, serverActions);
+  const toolsForGemini = [...slimTools, DISCOVERY_TOOL, PAGE_STATE_TOOL];
+  const toolSummary = buildToolSummary(toolDefinitions, serverActions);
+  const systemPrompt = buildSystemPrompt(pageState, toolSummary, service.systemPromptPrefix);
+  const clientToolNames = new Set(toolDefinitions.map((t) => t.name));
+  return processGeminiTurn(
+    service,
+    history,
+    toolsForGemini,
+    systemPrompt,
+    clientToolNames,
+    fullToolLookup,
     pageState,
-    serverActionSummaries,
-    service.systemPromptPrefix
+    /* @__PURE__ */ new Set()
   );
-  const clientToolNames = new Set(toolDefinitions.map((t) => t.name));
-  return processGeminiTurn(service, history, tools, systemPrompt, clientToolNames);
+}
+const INTERACTIVE_TYPE = "interactive";
+function isInteractive(tag) {
+  if (!tag.type)
+    return false;
+  if (typeof tag.type === "string")
+    return tag.type === INTERACTIVE_TYPE;
+  if (Array.isArray(tag.type))
+    return tag.type.includes(INTERACTIVE_TYPE);
+  return false;
+}
+function extractDescription(desc) {
+  if (!desc)
+    return void 0;
+  if (typeof desc === "string")
+    return desc;
+  if (Array.isArray(desc))
+    return desc.join(" ");
+  return void 0;
+}
+function collectInteractiveDescriptions(tags) {
+  const result = [];
+  for (const tag of tags) {
+    if (isInteractive(tag)) {
+      const desc = extractDescription(tag.description);
+      if (desc) {
+        result.push({ refName: tag.tag, description: desc });
+      }
+    }
+    if (tag.tags) {
+      result.push(...collectInteractiveDescriptions(tag.tags));
+    }
+  }
+  return result;
+}
+let cachedDescriptions = null;
+function loadToolDescriptions(projectRoot) {
+  if (cachedDescriptions)
+    return cachedDescriptions;
+  const log = getLogger();
+  const descriptions = [];
+  const indexPath = path$1.join(projectRoot, "agent-kit", "plugins-index.yaml");
+  if (!fs$1.existsSync(indexPath)) {
+    log.info("[gemini-agent] No plugins-index.yaml found, skipping tool descriptions");
+    cachedDescriptions = descriptions;
+    return descriptions;
+  }
+  try {
+    const indexContent = fs$1.readFileSync(indexPath, "utf-8");
+    const pluginsIndex = yaml.load(indexContent);
+    if (!pluginsIndex?.plugins) {
+      cachedDescriptions = descriptions;
+      return descriptions;
+    }
+    for (const plugin of pluginsIndex.plugins) {
+      for (const contract of plugin.contracts || []) {
+        const contractPath = path$1.resolve(projectRoot, contract.path);
+        if (!fs$1.existsSync(contractPath)) {
+          log.info(`[gemini-agent] Contract file not found: ${contractPath}, skipping`);
+          continue;
+        }
+        try {
+          const contractContent = fs$1.readFileSync(contractPath, "utf-8");
+          const parsed = yaml.load(contractContent);
+          if (parsed?.tags) {
+            descriptions.push(...collectInteractiveDescriptions(parsed.tags));
+          }
+        } catch (err) {
+          log.warn(
+            `[gemini-agent] Failed to parse contract ${contractPath}: ${err.message}`
+          );
+        }
+      }
+    }
+    log.info(`[gemini-agent] Loaded ${descriptions.length} tool descriptions from contracts`);
+  } catch (err) {
+    log.warn(`[gemini-agent] Failed to load plugins-index.yaml: ${err.message}`);
+  }
+  cachedDescriptions = descriptions;
+  return descriptions;
 }
 const sendMessage = makeJayAction("geminiAgent.sendMessage").withServices(GEMINI_SERVICE).withHandler(async (input, service) => {
   const { message, history, toolDefinitions, pageState } = input;
@@ -344,6 +625,9 @@ const submitToolResults = makeJayAction("geminiAgent.submitToolResults").withSer
   ];
   return handleConversation(service, updatedHistory, toolDefinitions, pageState);
 });
+const getToolDescriptions = makeJayAction("geminiAgent.getToolDescriptions").withMethod("GET").withHandler(async () => {
+  return loadToolDescriptions(process.cwd());
+});
 async function fastRender() {
   const Pipeline = RenderPipeline.for();
   return Pipeline.ok({}).toPhaseOutput(() => ({
@@ -363,14 +647,20 @@ async function fastRender() {
 }
 const geminiChat = makeJayStackComponent().withProps().withFastRender(fastRender);
 export {
+  DISCOVERY_TOOL,
   GEMINI_SERVICE,
   GeminiService,
+  PAGE_STATE_TOOL,
   buildSystemPrompt,
+  buildToolSummary,
+  compactPageState,
   geminiChat,
+  getToolDescriptions,
   init,
   resolveToolCallTarget,
   sendMessage,
   setupGeminiAgent,
   submitToolResults,
-  toGeminiTools
+  toGeminiTools,
+  toSlimGeminiTools
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/gemini-agent-plugin",
-  "version": "0.13.0",
+  "version": "0.14.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",
@@ -33,18 +33,19 @@
   },
   "dependencies": {
     "@google/genai": "^0.14.0",
-    "@jay-framework/component": "^0.13.0",
-    "@jay-framework/fullstack-component": "^0.13.0",
-    "@jay-framework/runtime": "^0.13.0",
-    "@jay-framework/runtime-automation": "^0.13.0",
-    "@jay-framework/stack-client-runtime": "^0.13.0",
-    "@jay-framework/stack-server-runtime": "^0.13.0",
+    "@jay-framework/component": "^0.14.0",
+    "@jay-framework/fullstack-component": "^0.14.0",
+    "@jay-framework/logger": "^0.14.0",
+    "@jay-framework/runtime": "^0.14.0",
+    "@jay-framework/runtime-automation": "^0.14.0",
+    "@jay-framework/stack-client-runtime": "^0.14.0",
+    "@jay-framework/stack-server-runtime": "^0.14.0",
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {
-    "@jay-framework/compiler-jay-stack": "^0.13.0",
-    "@jay-framework/dev-environment": "^0.13.0",
-    "@jay-framework/jay-cli": "^0.13.0",
+    "@jay-framework/compiler-jay-stack": "^0.14.0",
+    "@jay-framework/dev-environment": "^0.14.0",
+    "@jay-framework/jay-cli": "^0.14.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.15.21",
     "rimraf": "^5.0.5",

package/plugin.yaml

@@ -10,6 +10,7 @@ actions:
     action: send-message.jay-action
   - name: submitToolResults
     action: submit-tool-results.jay-action
+  - name: getToolDescriptions
 setup:
   handler: setupGeminiAgent
   description: Configure Gemini API key