@rcrsr/rill-ext-gemini 0.8.6 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # @rcrsr/rill-ext-gemini
 
-[rill](https://rill.run) extension for [Google Gemini](https://ai.google.dev/docs) API integration. Provides `message`, `messages`, `embed`, `embed_batch`, and `tool_loop` host functions.
+[rill](https://rill.run) extension for [Google Gemini](https://ai.google.dev/docs) API integration. Provides `message`, `messages`, `embed`, `embed_batch`, `tool_loop`, and `generate` host functions.
 
 > **Experimental.** Breaking changes will occur before stabilization.
 
@@ -36,131 +36,15 @@ const result = await execute(parse(script), ctx);
 dispose?.();
 ```
 
-## Host Functions
-
-All functions return a dict with `content`, `model`, `usage`, `stop_reason`, `id`, and `messages`.
-
-### gemini::message(text, options?)
-
-Send a single message to Gemini.
-
-```rill
-gemini::message("Analyze this code for security issues") => $response
-$response.content -> log
-$response.usage.output -> log
-```
-
-### gemini::messages(messages, options?)
-
-Send a multi-turn conversation.
-
-```rill
-gemini::messages([
-  [role: "user", content: "What is rill?"],
-  [role: "assistant", content: "A scripting language for AI agents."],
-  [role: "user", content: "Show me an example."]
-]) => $response
-$response.content -> log
-```
-
-### gemini::embed(text)
-
-Generate an embedding vector for text. Requires `embed_model` in config.
-
-```rill
-gemini::embed("Hello world") => $vector
-```
-
-### gemini::embed_batch(texts)
-
-Generate embedding vectors for multiple texts in a single API call.
-
-```rill
-gemini::embed_batch(["Hello", "World"]) => $vectors
-```
-
-### gemini::tool_loop(prompt, options)
-
-Execute a tool-use loop where the model calls rill functions iteratively.
-
-```rill
-gemini::tool_loop("Find the weather", [tools: $my_tools]) => $result
-$result.content -> log
-$result.turns -> log
-```
-
-## Configuration
-
-```typescript
-const ext = createGeminiExtension({
-  api_key: process.env.GOOGLE_API_KEY!,
-  model: 'gemini-2.0-flash',
-  temperature: 0.7,
-  max_tokens: 8192,
-  system: 'You are a helpful assistant.',
-  embed_model: 'text-embedding-004',
-});
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `api_key` | string | required | Google API key |
-| `model` | string | required | Model identifier |
-| `temperature` | number | undefined | Temperature (0.0-2.0) |
-| `base_url` | string | undefined | Custom API endpoint URL |
-| `max_tokens` | number | `8192` | Max tokens in response |
-| `max_retries` | number | undefined | Max retry attempts |
-| `timeout` | number | undefined | Request timeout in ms |
-| `system` | string | undefined | Default system instruction |
-| `embed_model` | string | undefined | Embedding model identifier |
-
-## Result Shape
-
-```typescript
-interface GeminiResult {
-  content: string;     // response text
-  model: string;       // model used
-  usage: {
-    input: number;     // prompt tokens
-    output: number;    // completion tokens
-  };
-  stop_reason: string; // finish reason
-  id: string;          // request ID
-  messages: Array<{    // full conversation history
-    role: string;
-    content: string;
-  }>;
-}
-```
-
-## Lifecycle
-
-Call `dispose()` on the extension to cancel pending requests:
-
-```typescript
-const ext = createGeminiExtension({ ... });
-// ... use extension ...
-await ext.dispose?.();
-```
-
-## Test Host
-
-A runnable example at `examples/test-host.ts` wires up the extension with the rill runtime:
-
-```bash
-pnpm exec tsx examples/test-host.ts
-pnpm exec tsx examples/test-host.ts -e 'gemini::message("Tell me a joke") -> log'
-pnpm exec tsx examples/test-host.ts script.rill
-```
+## Documentation
 
-Requires `GOOGLE_API_KEY` environment variable.
+See [full documentation](docs/extension-llm-gemini.md) for configuration, functions, error handling, events, and examples.
 
-## Documentation
+## Related
 
-| Document | Description |
-|----------|-------------|
-| [Extensions Guide](https://github.com/rcrsr/rill/blob/main/docs/integration-extensions.md) | Extension contract and patterns |
-| [Host API Reference](https://github.com/rcrsr/rill/blob/main/docs/ref-host-api.md) | Runtime context and host functions |
+- [rill](https://github.com/rcrsr/rill) — Core language runtime
+- [Extensions Guide](https://github.com/rcrsr/rill/blob/main/docs/integration-extensions.md) — Extension contract and patterns
+- [Host API Reference](https://github.com/rcrsr/rill/blob/main/docs/ref-host-api.md) — Runtime context and host functions
 
 ## License
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 // Generated by dts-bundle-generator v9.5.1
 
-import { ExtensionResult } from '@rcrsr/rill';
+import { ExtensionConfigSchema, ExtensionResult } from '@rcrsr/rill';
 
 /**
  * Base configuration for LLM extensions
@@ -73,12 +73,8 @@ export type GeminiExtensionConfig = LLMProviderConfig;
  * ```
  */
 export declare function createGeminiExtension(config: GeminiExtensionConfig): ExtensionResult;
-/**
- * @rcrsr/rill-ext-gemini
- *
- * Extension for Google Gemini API integration with rill scripts.
- */
 export declare const VERSION = "0.0.1";
+export declare const configSchema: ExtensionConfigSchema;
 
 export {
 	LLMProviderConfig as LLMExtensionConfig,

package/dist/index.js

@@ -4,11 +4,11 @@ import {
   Type
 } from "@google/genai";
 import {
-  RuntimeError as RuntimeError4,
+  RuntimeError as RuntimeError5,
   emitExtensionEvent,
   createVector,
   isVector,
-  isCallable as isCallable2
+  isDict as isDict2
 } from "@rcrsr/rill";
 
 // ../../shared/ext-llm/dist/validation.js
@@ -79,29 +79,108 @@ function mapProviderError(providerName, error, detect) {
 }
 
 // ../../shared/ext-llm/dist/tool-loop.js
-import { isCallable, isDict, RuntimeError as RuntimeError3 } from "@rcrsr/rill";
+import { invokeCallable, isCallable, isDict, isRuntimeCallable, RuntimeError as RuntimeError4 } from "@rcrsr/rill";
+
+// ../../shared/ext-llm/dist/schema.js
+import { RuntimeError as RuntimeError3 } from "@rcrsr/rill";
+var RILL_TYPE_MAP = {
+  string: "string",
+  number: "number",
+  bool: "boolean",
+  list: "array",
+  dict: "object",
+  vector: "object",
+  shape: "object"
+};
+function mapRillType(rillType) {
+  const jsonType = RILL_TYPE_MAP[rillType];
+  if (jsonType === void 0) {
+    throw new RuntimeError3("RILL-R004", `unsupported type: ${rillType}`);
+  }
+  return jsonType;
+}
+function buildJsonSchema(rillSchema) {
+  const properties = {};
+  const required = [];
+  for (const [key, value] of Object.entries(rillSchema)) {
+    if (typeof value === "string") {
+      properties[key] = buildProperty(value);
+    } else if (typeof value === "object" && value !== null) {
+      properties[key] = buildProperty(value);
+    } else {
+      throw new RuntimeError3("RILL-R004", `unsupported type: ${String(value)}`);
+    }
+    required.push(key);
+  }
+  return { type: "object", properties, required, additionalProperties: false };
+}
+function buildProperty(descriptor) {
+  if (typeof descriptor === "string") {
+    const jsonType2 = mapRillType(descriptor);
+    return { type: jsonType2 };
+  }
+  const rillType = descriptor["type"];
+  if (typeof rillType !== "string") {
+    throw new RuntimeError3("RILL-R004", `unsupported type: ${String(rillType)}`);
+  }
+  const jsonType = mapRillType(rillType);
+  const property = { type: jsonType };
+  const description = descriptor["description"];
+  if (typeof description === "string") {
+    property.description = description;
+  }
+  if ("enum" in descriptor) {
+    if (rillType !== "string") {
+      throw new RuntimeError3("RILL-R004", "enum is only valid for string type");
+    }
+    const enumValues = descriptor["enum"];
+    if (Array.isArray(enumValues)) {
+      property.enum = enumValues;
+    }
+  }
+  if (rillType === "list" && "items" in descriptor) {
+    const items = descriptor["items"];
+    if (typeof items === "string") {
+      property.items = buildProperty(items);
+    } else if (typeof items === "object" && items !== null) {
+      property.items = buildProperty(items);
+    }
+  }
+  if (rillType === "dict" && "properties" in descriptor) {
+    const nestedProps = descriptor["properties"];
+    if (typeof nestedProps === "object" && nestedProps !== null) {
+      const subSchema = buildJsonSchema(nestedProps);
+      property.properties = subSchema.properties;
+      property.required = subSchema.required;
+      property.additionalProperties = false;
+    }
+  }
+  return property;
+}
+
+// ../../shared/ext-llm/dist/tool-loop.js
 async function executeToolCall(toolName, toolInput, tools, context) {
   if (!isDict(tools)) {
-    throw new RuntimeError3("RILL-R004", "tools must be a dict mapping tool names to functions");
+    throw new RuntimeError4("RILL-R004", "tool_loop: tools must be a dict of name \u2192 callable");
   }
   const toolsDict = tools;
   const toolFn = toolsDict[toolName];
   if (toolFn === void 0 || toolFn === null) {
-    throw new RuntimeError3("RILL-R004", `Unknown tool: ${toolName}`);
+    throw new RuntimeError4("RILL-R004", `Unknown tool: ${toolName}`);
   }
   if (!isCallable(toolFn)) {
-    throw new RuntimeError3("RILL-R004", `Invalid tool input for ${toolName}: tool must be callable`);
+    throw new RuntimeError4("RILL-R004", `Invalid tool input for ${toolName}: tool must be callable`);
   }
   if (typeof toolInput !== "object" || toolInput === null) {
-    throw new RuntimeError3("RILL-R004", `Invalid tool input for ${toolName}: input must be an object`);
+    throw new RuntimeError4("RILL-R004", `Invalid tool input for ${toolName}: input must be an object`);
   }
   const callable = toolFn;
-  if (callable.kind !== "runtime" && callable.kind !== "application") {
-    throw new RuntimeError3("RILL-R004", `Invalid tool input for ${toolName}: tool must be application or runtime callable`);
+  if (callable.kind !== "runtime" && callable.kind !== "application" && callable.kind !== "script") {
+    throw new RuntimeError4("RILL-R004", `Invalid tool input for ${toolName}: tool must be application, runtime, or script callable`);
   }
   try {
     let args;
-    if (callable.kind === "application" && callable.params) {
+    if ((callable.kind === "application" || callable.kind === "script") && callable.params && callable.params.length > 0) {
       const params = callable.params;
       const inputDict = toolInput;
       args = params.map((param) => {
@@ -111,6 +190,12 @@ async function executeToolCall(toolName, toolInput, tools, context) {
     } else {
       args = [toolInput];
     }
+    if (callable.kind === "script") {
+      if (!context) {
+        throw new RuntimeError4("RILL-R004", `Invalid tool input for ${toolName}: script callable requires a runtime context`);
+      }
+      return await invokeCallable(callable, args, context);
+    }
     const ctx = context ?? {
       parent: void 0,
       variables: /* @__PURE__ */ new Map(),
@@ -119,77 +204,146 @@ async function executeToolCall(toolName, toolInput, tools, context) {
     const result = callable.fn(args, ctx);
     return result instanceof Promise ? await result : result;
   } catch (error) {
-    if (error instanceof RuntimeError3) {
+    if (error instanceof RuntimeError4) {
       throw error;
     }
     const message = error instanceof Error ? error.message : "Unknown error";
-    throw new RuntimeError3("RILL-R004", `Invalid tool input for ${toolName}: ${message}`);
+    throw new RuntimeError4("RILL-R004", `Invalid tool input for ${toolName}: ${message}`);
+  }
+}
+function sanitizeToolName(name) {
+  const match = name.match(/^[a-zA-Z0-9_-]*/);
+  const sanitized = match ? match[0] : "";
+  return sanitized.length > 0 ? sanitized : name;
+}
+function patchResponseToolCallNames(response, nameMap) {
+  if (!nameMap.size || !response || typeof response !== "object")
+    return;
+  const resp = response;
+  if (Array.isArray(resp["choices"])) {
+    for (const choice of resp["choices"]) {
+      const msg = choice?.["message"];
+      const tcs = msg?.["tool_calls"];
+      if (Array.isArray(tcs)) {
+        for (const tc of tcs) {
+          const fn = tc?.["function"];
+          if (fn && typeof fn["name"] === "string") {
+            const orig = fn["name"];
+            const san = nameMap.get(orig);
+            if (san !== void 0)
+              fn["name"] = san;
+          }
+        }
+      }
+    }
+  }
+  if (Array.isArray(resp["content"])) {
+    for (const block of resp["content"]) {
+      const b = block;
+      if (b?.["type"] === "tool_use" && typeof b?.["name"] === "string") {
+        const orig = b["name"];
+        const san = nameMap.get(orig);
+        if (san !== void 0)
+          b["name"] = san;
+      }
+    }
+  }
+  if (Array.isArray(resp["functionCalls"])) {
+    for (const fc of resp["functionCalls"]) {
+      const f = fc;
+      if (typeof f?.["name"] === "string") {
+        const orig = f["name"];
+        const san = nameMap.get(orig);
+        if (san !== void 0)
+          f["name"] = san;
+      }
+    }
+  }
+  if (Array.isArray(resp["candidates"])) {
+    for (const cand of resp["candidates"]) {
+      const content = cand?.["content"];
+      const parts = content?.["parts"];
+      if (Array.isArray(parts)) {
+        for (const part of parts) {
+          const fc = part?.["functionCall"];
+          if (fc && typeof fc["name"] === "string") {
+            const orig = fc["name"];
+            const san = nameMap.get(orig);
+            if (san !== void 0)
+              fc["name"] = san;
+          }
+        }
+      }
+    }
   }
 }
 async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent, maxTurns = 10, context) {
   if (tools === void 0) {
-    throw new RuntimeError3("RILL-R004", "tools parameter is required");
+    throw new RuntimeError4("RILL-R004", "tools parameter is required");
   }
   if (!isDict(tools)) {
-    throw new RuntimeError3("RILL-R004", "tools must be a dict mapping tool names to functions");
+    throw new RuntimeError4("RILL-R004", "tool_loop: tools must be a dict of name \u2192 callable");
   }
   const toolsDict = tools;
   const toolDescriptors = Object.entries(toolsDict).map(([name, fn]) => {
     const fnValue = fn;
+    if (isRuntimeCallable(fnValue)) {
+      throw new RuntimeError4("RILL-R004", `tool_loop: builtin "${name}" cannot be used as a tool \u2014 wrap in a closure`);
+    }
     if (!isCallable(fnValue)) {
-      throw new RuntimeError3("RILL-R004", `tool '${name}' must be callable function`);
+      throw new RuntimeError4("RILL-R004", `tool_loop: tool "${name}" is not a callable`);
     }
     const callable = fnValue;
-    const description = callable.kind === "application" && callable.description ? callable.description : "";
-    const properties = {};
-    const required = [];
-    if (callable.kind === "application" && callable.params) {
-      for (const param of callable.params) {
-        let jsonSchemaType;
-        switch (param.typeName) {
-          case "string":
-            jsonSchemaType = "string";
-            break;
-          case "number":
-            jsonSchemaType = "number";
-            break;
-          case "bool":
-            jsonSchemaType = "boolean";
-            break;
-          case "list":
-            jsonSchemaType = "array";
-            break;
-          case "dict":
-          case "vector":
-            jsonSchemaType = "object";
-            break;
-          case null:
-            jsonSchemaType = "string";
-            break;
-          default:
-            jsonSchemaType = "string";
-            break;
+    let description;
+    if (callable.kind === "script") {
+      description = callable.annotations["description"] ?? "";
+    } else {
+      description = callable.description ?? "";
+    }
+    let inputSchema;
+    const params = callable.kind === "application" ? callable.params ?? [] : callable.kind === "script" ? callable.params : [];
+    if (params.length > 0) {
+      const properties = {};
+      const required = [];
+      for (const param of params) {
+        const property = {};
+        if (param.typeName !== null) {
+          const descriptor = {
+            [param.name]: { type: param.typeName }
+          };
+          const schema = buildJsonSchema(descriptor);
+          const built = schema.properties[param.name];
+          if (built !== void 0) {
+            Object.assign(property, built);
+          }
         }
-        const property = {
-          type: jsonSchemaType
-        };
-        if (param.description) {
-          property["description"] = param.description;
+        let paramDesc;
+        if (callable.kind === "script") {
+          const annot = callable.paramAnnotations[param.name];
+          paramDesc = annot?.["description"] ?? "";
+        } else {
+          paramDesc = param.description ?? "";
+        }
+        if (paramDesc) {
+          property["description"] = paramDesc;
         }
         properties[param.name] = property;
         if (param.defaultValue === null) {
           required.push(param.name);
         }
       }
+      inputSchema = {
+        type: "object",
+        properties,
+        required
+      };
+    } else {
+      inputSchema = { type: "object", properties: {}, required: [] };
     }
     return {
       name,
       description,
-      input_schema: {
-        type: "object",
-        properties,
-        required
-      }
+      input_schema: inputSchema
     };
   });
   const providerTools = callbacks.buildTools(toolDescriptors);
@@ -206,7 +360,7 @@ async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent,
       response = await callbacks.callAPI(currentMessages, providerTools);
     } catch (error) {
       const message = error instanceof Error ? error.message : "Unknown error";
-      throw new RuntimeError3("RILL-R004", `Provider API error: ${message}`, void 0, { cause: error });
+      throw new RuntimeError4("RILL-R004", `Provider API error: ${message}`, void 0, { cause: error });
     }
     if (typeof response === "object" && response !== null && "usage" in response) {
       const usage = response["usage"];
@@ -218,7 +372,17 @@ async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent,
         totalOutputTokens += outputTokens;
       }
     }
-    const toolCalls = callbacks.extractToolCalls(response);
+    const rawToolCalls = callbacks.extractToolCalls(response);
+    const nameMap = /* @__PURE__ */ new Map();
+    const toolCalls = rawToolCalls?.map((tc) => {
+      const sanitized = sanitizeToolName(tc.name);
+      if (sanitized !== tc.name)
+        nameMap.set(tc.name, sanitized);
+      return sanitized !== tc.name ? { ...tc, name: sanitized } : tc;
+    }) ?? null;
+    if (nameMap.size > 0) {
+      patchResponseToolCallNames(response, nameMap);
+    }
     if (toolCalls === null || toolCalls.length === 0) {
       return {
         response,
@@ -243,7 +407,7 @@ async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent,
         const duration = Date.now() - toolStartTime;
         consecutiveErrors++;
         let originalError;
-        if (error instanceof RuntimeError3) {
+        if (error instanceof RuntimeError4) {
           const prefix = `Invalid tool input for ${name}: `;
           if (error.message.startsWith(prefix)) {
             originalError = error.message.slice(prefix.length);
@@ -268,12 +432,20 @@ async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent,
           duration
         });
         if (consecutiveErrors >= maxErrors) {
-          throw new RuntimeError3("RILL-R004", `Tool execution failed: ${maxErrors} consecutive errors`);
+          throw new RuntimeError4("RILL-R004", `Tool execution failed: ${maxErrors} consecutive errors (last: ${name}: ${originalError})`);
         }
       }
     }
+    const assistantMessage = callbacks.formatAssistantMessage(response);
+    if (assistantMessage != null) {
+      currentMessages.push(assistantMessage);
+    }
     const toolResultMessage = callbacks.formatToolResult(toolResults);
-    currentMessages.push(toolResultMessage);
+    if (Array.isArray(toolResultMessage)) {
+      currentMessages.push(...toolResultMessage);
+    } else {
+      currentMessages.push(toolResultMessage);
+    }
   }
   return {
     response: null,
@@ -301,6 +473,35 @@ var detectGeminiError = (error) => {
   }
   return null;
 };
+function toGeminiSchema(prop) {
+  let schemaType = Type.STRING;
+  if (prop.type === "number") schemaType = Type.NUMBER;
+  if (prop.type === "boolean") schemaType = Type.BOOLEAN;
+  if (prop.type === "integer") schemaType = Type.INTEGER;
+  if (prop.type === "array") schemaType = Type.ARRAY;
+  if (prop.type === "object") schemaType = Type.OBJECT;
+  const schema = { type: schemaType };
+  if (prop.description !== void 0) {
+    schema.description = prop.description;
+  }
+  if (prop.enum !== void 0) {
+    schema.enum = prop.enum;
+  }
+  if (prop.type === "array" && prop.items !== void 0) {
+    schema.items = toGeminiSchema(prop.items);
+  }
+  if (prop.type === "object" && prop.properties !== void 0) {
+    const nestedProperties = {};
+    for (const [key, nestedProp] of Object.entries(prop.properties)) {
+      nestedProperties[key] = toGeminiSchema(nestedProp);
+    }
+    schema.properties = nestedProperties;
+    if (prop.required !== void 0) {
+      schema.required = prop.required;
+    }
+  }
+  return schema;
+}
 function createGeminiExtension(config) {
   validateApiKey(config.api_key);
   validateModel(config.model);
@@ -343,7 +544,7 @@ function createGeminiExtension(config) {
           const text = args[0];
           const options = args[1] ?? {};
           if (text.trim().length === 0) {
-            throw new RuntimeError4("RILL-R004", "prompt text cannot be empty");
+            throw new RuntimeError5("RILL-R004", "prompt text cannot be empty");
           }
           const system = typeof options["system"] === "string" ? options["system"] : factorySystem;
           const maxTokens = typeof options["max_tokens"] === "number" ? options["max_tokens"] : factoryMaxTokens;
@@ -392,12 +593,14 @@ function createGeminiExtension(config) {
             subsystem: "extension:gemini",
             duration,
             model: factoryModel,
-            usage: result2.usage
+            usage: result2.usage,
+            request: contents,
+            content
           });
           return result2;
         } catch (error) {
           const duration = Date.now() - startTime;
-          const rillError = error instanceof RuntimeError4 ? error : mapProviderError("Gemini", error, detectGeminiError);
+          const rillError = error instanceof RuntimeError5 ? error : mapProviderError("Gemini", error, detectGeminiError);
           emitExtensionEvent(ctx, {
             event: "gemini:error",
             subsystem: "extension:gemini",
@@ -422,7 +625,7 @@ function createGeminiExtension(config) {
           const messages = args[0];
           const options = args[1] ?? {};
           if (messages.length === 0) {
-            throw new RuntimeError4(
+            throw new RuntimeError5(
               "RILL-R004",
               "messages list cannot be empty"
             );
@@ -433,18 +636,18 @@ function createGeminiExtension(config) {
           for (let i = 0; i < messages.length; i++) {
             const msg = messages[i];
             if (!msg || typeof msg !== "object" || !("role" in msg)) {
-              throw new RuntimeError4(
+              throw new RuntimeError5(
                 "RILL-R004",
                 "message missing required 'role' field"
               );
             }
             const role = msg["role"];
             if (role !== "user" && role !== "assistant" && role !== "tool") {
-              throw new RuntimeError4("RILL-R004", `invalid role '${role}'`);
+              throw new RuntimeError5("RILL-R004", `invalid role '${role}'`);
             }
             if (role === "user" || role === "tool") {
               if (!("content" in msg) || typeof msg["content"] !== "string") {
-                throw new RuntimeError4(
+                throw new RuntimeError5(
                   "RILL-R004",
                   `${role} message requires 'content'`
                 );
@@ -457,7 +660,7 @@ function createGeminiExtension(config) {
               const hasContent = "content" in msg && msg["content"];
               const hasToolCalls = "tool_calls" in msg && msg["tool_calls"];
               if (!hasContent && !hasToolCalls) {
-                throw new RuntimeError4(
+                throw new RuntimeError5(
                   "RILL-R004",
                   "assistant message requires 'content' or 'tool_calls'"
                 );
@@ -514,12 +717,14 @@ function createGeminiExtension(config) {
             subsystem: "extension:gemini",
             duration,
             model: factoryModel,
-            usage: result2.usage
+            usage: result2.usage,
+            request: contents,
+            content
           });
           return result2;
         } catch (error) {
           const duration = Date.now() - startTime;
-          const rillError = error instanceof RuntimeError4 ? error : mapProviderError("Gemini", error, detectGeminiError);
+          const rillError = error instanceof RuntimeError5 ? error : mapProviderError("Gemini", error, detectGeminiError);
           emitExtensionEvent(ctx, {
             event: "gemini:error",
             subsystem: "extension:gemini",
@@ -547,7 +752,7 @@ function createGeminiExtension(config) {
           });
           const embedding = response.embeddings?.[0];
           if (!embedding || !embedding.values || embedding.values.length === 0) {
-            throw new RuntimeError4(
+            throw new RuntimeError5(
               "RILL-R004",
               "Gemini: empty embedding returned"
             );
@@ -565,7 +770,7 @@ function createGeminiExtension(config) {
           return vector;
         } catch (error) {
           const duration = Date.now() - startTime;
-          const rillError = error instanceof RuntimeError4 ? error : mapProviderError("Gemini", error, detectGeminiError);
+          const rillError = error instanceof RuntimeError5 ? error : mapProviderError("Gemini", error, detectGeminiError);
           emitExtensionEvent(ctx, {
             event: "gemini:error",
             subsystem: "extension:gemini",
@@ -596,14 +801,14 @@ function createGeminiExtension(config) {
           });
           const vectors = [];
           if (!response.embeddings || response.embeddings.length === 0) {
-            throw new RuntimeError4(
+            throw new RuntimeError5(
               "RILL-R004",
               "Gemini: empty embeddings returned"
             );
           }
           for (const embedding of response.embeddings) {
             if (!embedding || !embedding.values || embedding.values.length === 0) {
-              throw new RuntimeError4(
+              throw new RuntimeError5(
                 "RILL-R004",
                 "Gemini: empty embedding returned"
               );
@@ -626,7 +831,7 @@ function createGeminiExtension(config) {
           return vectors;
         } catch (error) {
           const duration = Date.now() - startTime;
-          const rillError = error instanceof RuntimeError4 ? error : mapProviderError("Gemini", error, detectGeminiError);
+          const rillError = error instanceof RuntimeError5 ? error : mapProviderError("Gemini", error, detectGeminiError);
           emitExtensionEvent(ctx, {
             event: "gemini:error",
             subsystem: "extension:gemini",
@@ -651,39 +856,15 @@ function createGeminiExtension(config) {
           const prompt = args[0];
           const options = args[1] ?? {};
           if (prompt.trim().length === 0) {
-            throw new RuntimeError4("RILL-R004", "prompt text cannot be empty");
+            throw new RuntimeError5("RILL-R004", "prompt text cannot be empty");
           }
-          if (!("tools" in options) || !Array.isArray(options["tools"])) {
-            throw new RuntimeError4(
+          if (!("tools" in options) || !isDict2(options["tools"])) {
+            throw new RuntimeError5(
               "RILL-R004",
               "tool_loop requires 'tools' option"
             );
           }
-          const toolDescriptors = options["tools"];
-          const toolsDict = {};
-          for (const descriptor of toolDescriptors) {
-            const name = typeof descriptor["name"] === "string" ? descriptor["name"] : null;
-            if (!name) {
-              throw new RuntimeError4(
-                "RILL-R004",
-                "tool descriptor missing name"
-              );
-            }
-            const toolFnValue = descriptor["fn"];
-            if (!toolFnValue) {
-              throw new RuntimeError4(
-                "RILL-R004",
-                `tool '${name}' missing fn property`
-              );
-            }
-            if (!isCallable2(toolFnValue)) {
-              throw new RuntimeError4(
-                "RILL-R004",
-                `tool '${name}' fn must be callable`
-              );
-            }
-            toolsDict[name] = toolFnValue;
-          }
+          const toolsDict = options["tools"];
           const system = typeof options["system"] === "string" ? options["system"] : factorySystem;
           const maxTokens = typeof options["max_tokens"] === "number" ? options["max_tokens"] : factoryMaxTokens;
           const maxTurns = typeof options["max_turns"] === "number" ? options["max_turns"] : 10;
@@ -778,6 +959,21 @@ function createGeminiExtension(config) {
                 };
               });
             },
+            // Extract the model's content from Gemini response for conversation history
+            formatAssistantMessage: (response2) => {
+              if (!response2 || typeof response2 !== "object" || !("candidates" in response2)) {
+                return null;
+              }
+              const candidates = response2.candidates;
+              if (!Array.isArray(candidates) || candidates.length === 0) {
+                return null;
+              }
+              const candidate = candidates[0];
+              if (!candidate || typeof candidate !== "object" || !("content" in candidate)) {
+                return null;
+              }
+              return candidate.content;
+            },
             // Format tool results into Gemini message format
             formatToolResult: (toolResults) => {
               const functionResponseParts = toolResults.map((tr) => ({
@@ -810,7 +1006,8 @@ function createGeminiExtension(config) {
                 ...data
               });
             },
-            maxTurns
+            maxTurns,
+            ctx
           );
           const response = loopResult.response;
           const content = response && typeof response === "object" && "text" in response ? response.text ?? "" : "";
@@ -832,12 +1029,14 @@ function createGeminiExtension(config) {
             subsystem: "extension:gemini",
             turns: result2.turns,
             total_duration: duration,
-            usage: result2.usage
+            usage: result2.usage,
+            request: contents,
+            content
           });
           return result2;
         } catch (error) {
           const duration = Date.now() - startTime;
-          const rillError = error instanceof RuntimeError4 ? error : mapProviderError("Gemini", error, detectGeminiError);
+          const rillError = error instanceof RuntimeError5 ? error : mapProviderError("Gemini", error, detectGeminiError);
           emitExtensionEvent(ctx, {
             event: "gemini:error",
             subsystem: "extension:gemini",
@@ -849,6 +1048,130 @@ function createGeminiExtension(config) {
       },
       description: "Execute tool-use loop with Gemini API",
       returnType: "dict"
+    },
+    // IR-3: gemini::generate
+    generate: {
+      params: [
+        { name: "prompt", type: "string" },
+        { name: "options", type: "dict" }
+      ],
+      fn: async (args, ctx) => {
+        const startTime = Date.now();
+        try {
+          const prompt = args[0];
+          const options = args[1] ?? {};
+          if (!("schema" in options) || options["schema"] === null || options["schema"] === void 0) {
+            throw new RuntimeError5(
+              "RILL-R004",
+              "generate requires 'schema' option"
+            );
+          }
+          const rillSchema = options["schema"];
+          const jsonSchema = buildJsonSchema(rillSchema);
+          const geminiProperties = {};
+          for (const [key, prop] of Object.entries(jsonSchema.properties)) {
+            geminiProperties[key] = toGeminiSchema(prop);
+          }
+          const responseSchema = {
+            type: Type.OBJECT,
+            properties: geminiProperties,
+            required: jsonSchema.required
+          };
+          const system = typeof options["system"] === "string" ? options["system"] : factorySystem;
+          const maxTokens = typeof options["max_tokens"] === "number" ? options["max_tokens"] : factoryMaxTokens;
+          const contents = [];
+          if ("messages" in options && Array.isArray(options["messages"])) {
+            const prependedMessages = options["messages"];
+            for (const msg of prependedMessages) {
+              if (typeof msg === "object" && msg !== null && "role" in msg && "content" in msg) {
+                const role = msg["role"];
+                if (role === "user") {
+                  contents.push({
+                    role: "user",
+                    parts: [{ text: msg["content"] }]
+                  });
+                } else if (role === "assistant") {
+                  contents.push({
+                    role: "model",
+                    parts: [{ text: msg["content"] }]
+                  });
+                }
+              }
+            }
+          }
+          contents.push({
+            role: "user",
+            parts: [{ text: prompt }]
+          });
+          const apiConfig = {
+            responseSchema,
+            responseMimeType: "application/json"
+          };
+          if (system !== void 0) {
+            apiConfig.systemInstruction = system;
+          }
+          if (maxTokens !== void 0) {
+            apiConfig.maxOutputTokens = maxTokens;
+          }
+          if (factoryTemperature !== void 0) {
+            apiConfig.temperature = factoryTemperature;
+          }
+          const response = await client.models.generateContent({
+            model: factoryModel,
+            contents,
+            config: apiConfig
+          });
+          const raw = response.text ?? "";
+          let data;
+          try {
+            data = JSON.parse(raw);
+          } catch (parseError) {
+            const detail = parseError instanceof Error ? parseError.message : String(parseError);
+            throw new RuntimeError5(
+              "RILL-R004",
+              `generate: failed to parse response JSON: ${detail}`
+            );
+          }
+          const inputTokens = response.usageMetadata?.promptTokenCount ?? 0;
+          const outputTokens = response.usageMetadata?.candidatesTokenCount ?? 0;
+          const stopReason = response.candidates?.[0]?.finishReason ?? "stop";
+          const id = response.responseId ?? "";
+          const generateResult = {
+            data,
+            raw,
+            model: factoryModel,
+            usage: {
+              input: inputTokens,
+              output: outputTokens
+            },
+            stop_reason: stopReason,
+            id
+          };
+          const duration = Date.now() - startTime;
+          emitExtensionEvent(ctx, {
+            event: "gemini:generate",
+            subsystem: "extension:gemini",
+            duration,
+            model: factoryModel,
+            usage: generateResult.usage,
+            request: contents,
+            content: raw
+          });
+          return generateResult;
+        } catch (error) {
+          const duration = Date.now() - startTime;
+          const rillError = error instanceof RuntimeError5 ? error : mapProviderError("Gemini", error, detectGeminiError);
+          emitExtensionEvent(ctx, {
+            event: "gemini:error",
+            subsystem: "extension:gemini",
+            error: rillError.message,
+            duration
+          });
+          throw rillError;
+        }
+      },
+      description: "Generate structured output from Gemini API",
+      returnType: "dict"
     }
   };
   result.dispose = dispose;
@@ -857,7 +1180,19 @@ function createGeminiExtension(config) {
 
 // src/index.ts
 var VERSION = "0.0.1";
+var configSchema = {
+  api_key: { type: "string", required: true, secret: true },
+  model: { type: "string", required: true },
+  base_url: { type: "string" },
+  temperature: { type: "number" },
+  max_tokens: { type: "number" },
+  timeout: { type: "number" },
+  max_retries: { type: "number" },
+  system: { type: "string" },
+  embed_model: { type: "string" }
+};
 export {
   VERSION,
+  configSchema,
   createGeminiExtension
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rcrsr/rill-ext-gemini",
-  "version": "0.8.6",
+  "version": "0.9.0",
   "description": "rill extension for Google Gemini API integration",
   "license": "MIT",
   "author": "Andre Bremer",
@@ -17,14 +17,14 @@
     "scripting"
   ],
   "peerDependencies": {
-    "@rcrsr/rill": "^0.8.6"
+    "@rcrsr/rill": "^0.9.0"
   },
   "devDependencies": {
-    "@types/node": "^25.2.3",
+    "@rcrsr/rill": "^0.9.0",
+    "@types/node": "^25.3.0",
     "dts-bundle-generator": "^9.5.1",
-    "tsup": "^8.5.0",
-    "undici-types": "^7.21.0",
-    "@rcrsr/rill": "^0.8.6",
+    "tsup": "^8.5.1",
+    "undici-types": "^7.22.0",
     "@rcrsr/rill-ext-llm-shared": "^0.0.1"
   },
   "files": [
@@ -32,18 +32,18 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/rcrsr/rill.git",
+    "url": "git+https://github.com/rcrsr/rill-ext.git",
     "directory": "packages/ext/llm-gemini"
   },
-  "homepage": "https://rill.run/docs/extensions/gemini/",
+  "homepage": "https://github.com/rcrsr/rill-ext/tree/main/packages/ext/llm-gemini#readme",
   "bugs": {
-    "url": "https://github.com/rcrsr/rill/issues"
+    "url": "https://github.com/rcrsr/rill-ext/issues"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@google/genai": "^1.40.0"
+    "@google/genai": "^1.42.0"
   },
   "scripts": {
     "build": "tsup && dts-bundle-generator --config dts-bundle-generator.config.cjs",