ai-sdk-provider-gemini-cli-agentic 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,296 @@
+# ai-sdk-provider-gemini-cli-agentic
+
+[![npm version](https://img.shields.io/npm/v/ai-sdk-provider-gemini-cli-agentic.svg)](https://www.npmjs.com/package/ai-sdk-provider-gemini-cli-agentic)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+[AI SDK](https://sdk.vercel.ai/docs) v6 provider for [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) agentic mode.
+
+This provider spawns `gemini` as a subprocess with `--output-format stream-json`, enabling full agentic capabilities like file system access, code editing, and tool execution through the AI SDK interface.
+
+## Features
+
+- **Full Agentic Support**: Access all Gemini CLI tools (file system, code editing, shell commands, etc.)
+- **Streaming**: Real-time streaming of text and tool calls
+- **Tool Streaming**: Watch tool calls and results as they happen
+- **Approval Modes**: Control tool approval behavior (`default`, `auto_edit`, `yolo`)
+- **Sandbox Mode**: Run in a sandboxed environment for safety
+- **Session Resume**: Resume previous sessions
+- **MCP Server Support**: Integrate with MCP servers
+- **Custom Logging**: Built-in logging with customization support
+- **AI SDK v6 Compatible**: Works with `generateText`, `streamText`, and `streamObject`
+
+## Requirements
+
+- [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed and authenticated (or use `allowNpx: true`)
+- Node.js 18+
+- AI SDK v6+
+
+## Installation
+
+```bash
+npm install ai-sdk-provider-gemini-cli-agentic ai
+```
+
+### Install Gemini CLI (Optional)
+
+**Option 1**: Install globally (recommended for frequent use):
+
+```bash
+npm install -g @google/gemini-cli
+```
+
+**Option 2**: Use `allowNpx: true` to run via npx (no global install needed):
+
+```javascript
+geminiCli('auto', { allowNpx: true })
+```
+
+Then authenticate:
+
+```bash
+gemini auth login
+```
+
+## Quick Start
+
+```javascript
+import { geminiCli } from 'ai-sdk-provider-gemini-cli-agentic';
+import { generateText, streamText } from 'ai';
+
+// Basic usage
+const { text } = await generateText({
+  model: geminiCli('gemini-2.5-flash'),
+  prompt: 'List files in the current directory',
+});
+
+// Streaming
+const result = streamText({
+  model: geminiCli('auto', { cwd: process.cwd() }),
+  prompt: 'Explain the structure of this project',
+});
+
+for await (const chunk of result.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+## Configuration
+
+### Provider Settings
+
+```javascript
+import { createGeminiCli } from 'ai-sdk-provider-gemini-cli-agentic';
+
+const provider = createGeminiCli({
+  defaultSettings: {
+    geminiPath: '/usr/local/bin/gemini', // Custom CLI path
+    cwd: '/path/to/project',              // Working directory
+    approvalMode: 'auto_edit',            // Approval mode
+    sandbox: true,                         // Enable sandbox
+    verbose: true,                         // Verbose output
+  },
+});
+
+const model = provider('gemini-2.5-flash');
+```
+
+### Per-Model Settings
+
+```javascript
+const model = geminiCli('gemini-2.5-flash', {
+  cwd: process.cwd(),
+  approvalMode: 'yolo',
+  sandbox: false,
+  includeDirectories: ['../shared-lib'],
+  allowedTools: ['read_file', 'write_file', 'list_directory'],
+  allowedMcpServerNames: ['filesystem'],
+  resume: 'latest', // or session index number
+  env: {
+    MY_VAR: 'value',
+  },
+});
+```
+
+### Settings Reference
+
+| Setting | Type | Description |
+|---------|------|-------------|
+| `geminiPath` | `string` | Path to Gemini CLI executable (default: `'gemini'`) |
+| `allowNpx` | `boolean` | Allow falling back to `npx @google/gemini-cli` if CLI not found |
+| `cwd` | `string` | Working directory for CLI operations |
+| `approvalMode` | `'default' \| 'auto_edit' \| 'yolo'` | Tool approval behavior |
+| `yolo` | `boolean` | Auto-approve all operations (alias for `approvalMode: 'yolo'`) |
+| `sandbox` | `boolean` | Enable sandbox mode |
+| `includeDirectories` | `string[]` | Additional directories to include |
+| `allowedTools` | `string[]` | Tools allowed without confirmation |
+| `allowedMcpServerNames` | `string[]` | Allowed MCP server names |
+| `resume` | `string \| boolean` | Resume session (`'latest'`, index, or `true`) |
+| `model` | `string` | Override model name |
+| `env` | `Record<string, string>` | Environment variables |
+| `verbose` | `boolean` | Enable verbose logging |
+| `logger` | `Logger \| false` | Custom logger or `false` to disable |
+
+## Approval Modes
+
+| Mode | Description |
+|------|-------------|
+| `default` | Prompt for approval on each tool operation |
+| `auto_edit` | Auto-approve file editing tools |
+| `yolo` | Auto-approve all tools (use with caution) |
+
+```javascript
+// Conservative (default)
+geminiCli('auto', { approvalMode: 'default' })
+
+// Auto-approve edits only
+geminiCli('auto', { approvalMode: 'auto_edit' })
+
+// Full automation (dangerous!)
+geminiCli('auto', { approvalMode: 'yolo' })
+// or
+geminiCli('auto', { yolo: true })
+```
+
+## Streaming with Tool Calls
+
+```javascript
+import { geminiCli } from 'ai-sdk-provider-gemini-cli-agentic';
+import { streamText } from 'ai';
+
+const result = streamText({
+  model: geminiCli('auto', { cwd: process.cwd() }),
+  prompt: 'Read package.json and explain the dependencies',
+});
+
+for await (const part of result.fullStream) {
+  switch (part.type) {
+    case 'text-delta':
+      process.stdout.write(part.textDelta);
+      break;
+    case 'tool-call':
+      console.log(`\n🔧 Tool: ${part.toolName}`);
+      console.log(`   Args: ${JSON.stringify(part.args)}`);
+      break;
+    case 'tool-result':
+      console.log(`   Result: ${part.result?.slice(0, 100)}...`);
+      break;
+  }
+}
+```
+
+## Logging
+
+### Default Logger
+
+```javascript
+const model = geminiCli('auto', {
+  verbose: true,  // Enable info-level logging
+});
+```
+
+### Custom Logger
+
+```javascript
+const model = geminiCli('auto', {
+  logger: {
+    debug: (msg) => console.debug('[DEBUG]', msg),
+    info: (msg) => console.info('[INFO]', msg),
+    warn: (msg) => console.warn('[WARN]', msg),
+    error: (msg) => console.error('[ERROR]', msg),
+  },
+});
+```
+
+### Disable Logging
+
+```javascript
+const model = geminiCli('auto', {
+  logger: false,
+});
+```
+
+## Error Handling
+
+```javascript
+import { geminiCli, isAuthenticationError } from 'ai-sdk-provider-gemini-cli-agentic';
+import { generateText } from 'ai';
+
+try {
+  const { text } = await generateText({
+    model: geminiCli('auto'),
+    prompt: 'Hello',
+  });
+} catch (error) {
+  if (isAuthenticationError(error)) {
+    console.error('Please run: gemini auth login');
+  } else {
+    console.error('Error:', error.message);
+  }
+}
+```
+
+## Models
+
+The model ID is passed directly to Gemini CLI's `-m` flag:
+
+```javascript
+// Use auto model selection
+geminiCli('auto')
+
+// Specific models
+geminiCli('gemini-2.5-flash')
+geminiCli('gemini-2.5-pro')
+geminiCli('gemini-3')
+```
+
+## Examples
+
+See the [`examples/`](./examples/) directory for more usage examples:
+
+- `basic-usage.mjs` - Simple text generation
+- `streaming.mjs` - Streaming responses
+- `streaming-tool-calls.mjs` - Watching tool execution
+- `conversation-history.mjs` - Multi-turn conversations
+- `custom-config.mjs` - Advanced configuration
+- `permissions-and-sandbox.mjs` - Approval modes and sandbox
+- `error-handling.mjs` - Error handling patterns
+- `logging-*.mjs` - Various logging configurations
+
+Run examples:
+
+```bash
+cd examples
+node basic-usage.mjs
+```
+
+## Limitations
+
+- **Interactive Prompts**: The provider cannot handle Gemini CLI's interactive approval prompts. Use `approvalMode: 'yolo'` or `approvalMode: 'auto_edit'` for automation.
+- **No Image Input**: Image/multimodal input is not supported (text only).
+- **No Embedding/Image Models**: Only language model is supported (`embeddingModel` and `imageModel` throw errors).
+- **Subprocess Overhead**: Each call spawns a new subprocess; not suitable for high-frequency requests.
+
+## CLI Flags Mapping
+
+| Provider Setting | CLI Flag |
+|-----------------|----------|
+| `cwd` | Process working directory |
+| `approvalMode` | `--approval-mode` |
+| `yolo` | `-y` / `--yolo` |
+| `sandbox` | `-s` / `--sandbox` |
+| `includeDirectories` | `--include-directories` |
+| `allowedTools` | `--allowed-tools` |
+| `allowedMcpServerNames` | `--allowed-mcp-server-names` |
+| `resume` | `-r` / `--resume` |
+| `model` | `-m` / `--model` |
+| *(always set)* | `--output-format stream-json` |
+
+## License
+
+MIT
+
+## Related
+
+- [AI SDK](https://sdk.vercel.ai/docs) - The AI SDK by Vercel
+- [Gemini CLI](https://github.com/google-gemini/gemini-cli) - Google's Gemini CLI
+- [ai-sdk-provider-codex-cli](https://github.com/J3n5en/ai-sdk-provider-codex-cli) - Similar provider for OpenAI Codex CLI

package/dist/index.cjs

@@ -216,6 +216,17 @@ function mapGeminiFinishReason(status) {
       return { unified: "stop", raw: status };
   }
 }
+function resolveGeminiPath(explicitPath, allowNpx) {
+  if (explicitPath) {
+    const lower = explicitPath.toLowerCase();
+    if (lower.endsWith(".js") || lower.endsWith(".mjs") || lower.endsWith(".cjs")) {
+      return { cmd: "node", args: [explicitPath] };
+    }
+    return { cmd: explicitPath, args: [] };
+  }
+  if (allowNpx) return { cmd: "npx", args: ["-y", "@google/gemini-cli"] };
+  return { cmd: "gemini", args: [] };
+}
 var GeminiCliLanguageModel = class {
   specificationVersion = "v3";
   provider = "gemini-cli";
@@ -248,9 +259,11 @@ var GeminiCliLanguageModel = class {
       allowedMcpServerNames: providerOptions.allowedMcpServerNames ?? this.settings.allowedMcpServerNames
     };
   }
-  buildArgs(promptText, settings = this.settings) {
-    const cmd = settings.geminiPath ?? "gemini";
-    const args = [];
+  buildArgs(settings = this.settings) {
+    const base = resolveGeminiPath(settings.geminiPath, settings.allowNpx);
+    const cmd = base.cmd;
+    const args = [...base.args];
+    const shell = process.platform === "win32" && (base.cmd === "npx" || base.cmd === "gemini");
     args.push("--output-format", "stream-json");
     if (this.modelId && this.modelId !== "auto") {
       args.push("-m", this.modelId);
@@ -281,12 +294,12 @@ var GeminiCliLanguageModel = class {
         args.push("--resume", "latest");
       }
     }
-    args.push(promptText);
+    args.push("-");
     const env = {
       ...process.env,
       ...settings.env || {}
     };
-    return { cmd, args, env, cwd: settings.cwd };
+    return { cmd, args, env, cwd: settings.cwd, shell };
   }
   mapWarnings(options) {
     const unsupported = [];
@@ -333,14 +346,16 @@ var GeminiCliLanguageModel = class {
       schema: geminiCliProviderOptionsSchema
     });
     const effectiveSettings = this.mergeSettings(providerOptions);
-    const { cmd, args, env, cwd } = this.buildArgs(promptText, effectiveSettings);
-    this.logger.debug(`[gemini-cli] Executing: ${cmd} ${args.slice(0, -1).join(" ")} [prompt]`);
+    const { cmd, args, env, cwd, shell } = this.buildArgs(effectiveSettings);
+    this.logger.debug(`[gemini-cli] Executing: ${cmd} ${args.join(" ")}`);
     let text = "";
     let usage = createEmptyUsage();
     let finishReason = { unified: "stop", raw: void 0 };
     const content = [];
     const toolResults = /* @__PURE__ */ new Map();
-    const child = child_process.spawn(cmd, args, { env, cwd, stdio: ["ignore", "pipe", "pipe"] });
+    const child = child_process.spawn(cmd, args, { env, cwd, shell, stdio: ["pipe", "pipe", "pipe"] });
+    child.stdin.write(promptText);
+    child.stdin.end();
     let onAbort;
     if (options.abortSignal) {
       if (options.abortSignal.aborted) {
@@ -465,14 +480,16 @@ var GeminiCliLanguageModel = class {
       schema: geminiCliProviderOptionsSchema
     });
     const effectiveSettings = this.mergeSettings(providerOptions);
-    const { cmd, args, env, cwd } = this.buildArgs(promptText, effectiveSettings);
-    this.logger.debug(`[gemini-cli] Streaming: ${cmd} ${args.slice(0, -1).join(" ")} [prompt]`);
+    const { cmd, args, env, cwd, shell } = this.buildArgs(effectiveSettings);
+    this.logger.debug(`[gemini-cli] Streaming: ${cmd} ${args.join(" ")}`);
     const model = this;
     const abortSignal = options.abortSignal;
     const stream = new ReadableStream({
       start(controller) {
         const startTime = Date.now();
-        const child = child_process.spawn(cmd, args, { env, cwd, stdio: ["ignore", "pipe", "pipe"] });
+        const child = child_process.spawn(cmd, args, { env, cwd, shell, stdio: ["pipe", "pipe", "pipe"] });
+        child.stdin.write(promptText);
+        child.stdin.end();
         controller.enqueue({ type: "stream-start", warnings });
         let stderr = "";
         let lastUsage;
@@ -609,6 +626,7 @@ var loggerFunctionSchema = zod.z.object({
 });
 var settingsSchema = zod.z.object({
   geminiPath: zod.z.string().optional(),
+  allowNpx: zod.z.boolean().optional(),
   cwd: zod.z.string().optional(),
   includeDirectories: zod.z.array(zod.z.string().min(1)).optional(),
   approvalMode: zod.z.enum(["default", "auto_edit", "yolo"]).optional(),

package/dist/index.d.cts

@@ -25,6 +25,10 @@ interface GeminiCliSettings {
      * @default 'gemini' (uses system PATH)
      */
     geminiPath?: string;
+    /**
+     * Allow falling back to `npx @google/gemini-cli` if the binary cannot be resolved.
+     */
+    allowNpx?: boolean;
     /**
      * Working directory for CLI operations.
      */

package/dist/index.d.ts

@@ -25,6 +25,10 @@ interface GeminiCliSettings {
      * @default 'gemini' (uses system PATH)
      */
     geminiPath?: string;
+    /**
+     * Allow falling back to `npx @google/gemini-cli` if the binary cannot be resolved.
+     */
+    allowNpx?: boolean;
     /**
      * Working directory for CLI operations.
      */

package/dist/index.js

@@ -214,6 +214,17 @@ function mapGeminiFinishReason(status) {
       return { unified: "stop", raw: status };
   }
 }
+function resolveGeminiPath(explicitPath, allowNpx) {
+  if (explicitPath) {
+    const lower = explicitPath.toLowerCase();
+    if (lower.endsWith(".js") || lower.endsWith(".mjs") || lower.endsWith(".cjs")) {
+      return { cmd: "node", args: [explicitPath] };
+    }
+    return { cmd: explicitPath, args: [] };
+  }
+  if (allowNpx) return { cmd: "npx", args: ["-y", "@google/gemini-cli"] };
+  return { cmd: "gemini", args: [] };
+}
 var GeminiCliLanguageModel = class {
   specificationVersion = "v3";
   provider = "gemini-cli";
@@ -246,9 +257,11 @@ var GeminiCliLanguageModel = class {
       allowedMcpServerNames: providerOptions.allowedMcpServerNames ?? this.settings.allowedMcpServerNames
     };
   }
-  buildArgs(promptText, settings = this.settings) {
-    const cmd = settings.geminiPath ?? "gemini";
-    const args = [];
+  buildArgs(settings = this.settings) {
+    const base = resolveGeminiPath(settings.geminiPath, settings.allowNpx);
+    const cmd = base.cmd;
+    const args = [...base.args];
+    const shell = process.platform === "win32" && (base.cmd === "npx" || base.cmd === "gemini");
     args.push("--output-format", "stream-json");
     if (this.modelId && this.modelId !== "auto") {
       args.push("-m", this.modelId);
@@ -279,12 +292,12 @@ var GeminiCliLanguageModel = class {
         args.push("--resume", "latest");
       }
     }
-    args.push(promptText);
+    args.push("-");
     const env = {
       ...process.env,
       ...settings.env || {}
     };
-    return { cmd, args, env, cwd: settings.cwd };
+    return { cmd, args, env, cwd: settings.cwd, shell };
   }
   mapWarnings(options) {
     const unsupported = [];
@@ -331,14 +344,16 @@ var GeminiCliLanguageModel = class {
       schema: geminiCliProviderOptionsSchema
     });
     const effectiveSettings = this.mergeSettings(providerOptions);
-    const { cmd, args, env, cwd } = this.buildArgs(promptText, effectiveSettings);
-    this.logger.debug(`[gemini-cli] Executing: ${cmd} ${args.slice(0, -1).join(" ")} [prompt]`);
+    const { cmd, args, env, cwd, shell } = this.buildArgs(effectiveSettings);
+    this.logger.debug(`[gemini-cli] Executing: ${cmd} ${args.join(" ")}`);
     let text = "";
     let usage = createEmptyUsage();
     let finishReason = { unified: "stop", raw: void 0 };
     const content = [];
     const toolResults = /* @__PURE__ */ new Map();
-    const child = spawn(cmd, args, { env, cwd, stdio: ["ignore", "pipe", "pipe"] });
+    const child = spawn(cmd, args, { env, cwd, shell, stdio: ["pipe", "pipe", "pipe"] });
+    child.stdin.write(promptText);
+    child.stdin.end();
     let onAbort;
     if (options.abortSignal) {
       if (options.abortSignal.aborted) {
@@ -463,14 +478,16 @@ var GeminiCliLanguageModel = class {
       schema: geminiCliProviderOptionsSchema
     });
     const effectiveSettings = this.mergeSettings(providerOptions);
-    const { cmd, args, env, cwd } = this.buildArgs(promptText, effectiveSettings);
-    this.logger.debug(`[gemini-cli] Streaming: ${cmd} ${args.slice(0, -1).join(" ")} [prompt]`);
+    const { cmd, args, env, cwd, shell } = this.buildArgs(effectiveSettings);
+    this.logger.debug(`[gemini-cli] Streaming: ${cmd} ${args.join(" ")}`);
     const model = this;
     const abortSignal = options.abortSignal;
     const stream = new ReadableStream({
       start(controller) {
         const startTime = Date.now();
-        const child = spawn(cmd, args, { env, cwd, stdio: ["ignore", "pipe", "pipe"] });
+        const child = spawn(cmd, args, { env, cwd, shell, stdio: ["pipe", "pipe", "pipe"] });
+        child.stdin.write(promptText);
+        child.stdin.end();
         controller.enqueue({ type: "stream-start", warnings });
         let stderr = "";
         let lastUsage;
@@ -607,6 +624,7 @@ var loggerFunctionSchema = z.object({
 });
 var settingsSchema = z.object({
   geminiPath: z.string().optional(),
+  allowNpx: z.boolean().optional(),
   cwd: z.string().optional(),
   includeDirectories: z.array(z.string().min(1)).optional(),
   approvalMode: z.enum(["default", "auto_edit", "yolo"]).optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-sdk-provider-gemini-cli-agentic",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "AI SDK v6 provider for Google Gemini CLI agentic mode",
   "keywords": [
     "ai-sdk",