@k2wanko/gemini-cli-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 k2wanko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @k2wanko/gemini-cli-sdk
+
+A lightweight, type-safe SDK for building non-interactive AI agents powered by Google Gemini.
+Built on top of `@google/gemini-cli-core`.
+
+## Features
+
+- **Skill support** — Load skill directories compatible with Gemini CLI's skill format
+- **Non-interactive by default** — All tool calls are auto-approved, designed for headless agent usage
+
+## Install
+
+```bash
+npm install @k2wanko/gemini-cli-sdk
+```
+
+## Quick Start
+
+```ts
+import { GeminiAgent, GeminiEventType } from "@k2wanko/gemini-cli-sdk";
+
+const agent = new GeminiAgent({
+  instructions: "You are a friendly assistant. Keep responses short.",
+});
+
+for await (const event of agent.sendStream("Say hello")) {
+  if (event.type === GeminiEventType.Content) {
+    process.stdout.write(String(event.value));
+  }
+}
+```
+
+## Defining Custom Tools
+
+```ts
+import { GeminiAgent, defineTool, z } from "@k2wanko/gemini-cli-sdk";
+
+const fetchUrl = defineTool(
+  {
+    name: "fetch_url",
+    description: "Fetch the content of a URL",
+    inputSchema: z.object({
+      url: z.string().url(),
+    }),
+  },
+  async (params) => {
+    const res = await fetch(params.url);
+    return res.text();
+  },
+);
+
+const agent = new GeminiAgent({
+  instructions: "You are a web research assistant.",
+  tools: [fetchUrl],
+});
+```
+
+## Using Skills
+
+Load skill directories to give the agent additional capabilities:
+
+```ts
+import { GeminiAgent, GeminiEventType, skillDir } from "@k2wanko/gemini-cli-sdk";
+
+const agent = new GeminiAgent({
+  instructions: "You are a browser automation assistant.",
+  skills: [
+    skillDir(new URL("skills", import.meta.url).pathname),
+  ],
+});
+
+for await (const event of agent.sendStream(
+  "Take a screenshot of https://example.com",
+)) {
+  if (event.type === GeminiEventType.Content) {
+    process.stdout.write(String(event.value));
+  }
+}
+```
+
+See [`examples/`](./examples/) for runnable samples.
+
+## Authentication
+
+This SDK uses the same authentication as `@google/gemini-cli-core`. Set up credentials via one of:
+
+- **Google Cloud ADC** (default): `gcloud auth application-default login`
+- **API Key**: Set `GEMINI_API_KEY` environment variable
+
+## License
+
+MIT

package/dist/agent.d.ts

@@ -0,0 +1,26 @@
+import { GeminiEventType, type ServerGeminiStreamEvent } from "@google/gemini-cli-core";
+import { type SessionContext } from "./context.js";
+import type { SkillRef } from "./skills.js";
+import { type ToolDef } from "./tool.js";
+export { GeminiEventType, type ServerGeminiStreamEvent };
+export interface GeminiAgentOptions {
+    instructions: string | ((ctx: SessionContext) => string | Promise<string>);
+    tools?: ToolDef<any>[];
+    skills?: SkillRef[];
+    model?: string;
+    cwd?: string;
+    debug?: boolean;
+}
+export declare class GeminiAgent {
+    private readonly config;
+    private readonly tools;
+    private readonly skillRefs;
+    private readonly instructions;
+    private instructionsLoaded;
+    constructor(options: GeminiAgentOptions);
+    sendStream(prompt: string, signal?: AbortSignal): AsyncGenerator<ServerGeminiStreamEvent>;
+    private initialize;
+    private resolveInstructions;
+    private buildScopedRegistry;
+    private extractToolCalls;
+}

package/dist/agent.js

@@ -0,0 +1,171 @@
+import { ActivateSkillTool, AuthType, Config, GeminiEventType, getAuthTypeFromEnv, loadSkillsFromDir, PolicyDecision, PREVIEW_GEMINI_MODEL_AUTO, scheduleAgentTools, } from "@google/gemini-cli-core";
+import { AgentFsImpl, AgentShellImpl } from "./context.js";
+import { SdkTool } from "./tool.js";
+export { GeminiEventType };
+export class GeminiAgent {
+    config;
+    tools;
+    skillRefs;
+    instructions;
+    instructionsLoaded = false;
+    constructor(options) {
+        this.instructions = options.instructions;
+        this.tools = options.tools ?? [];
+        this.skillRefs = options.skills ?? [];
+        const cwd = options.cwd ?? process.cwd();
+        const initialMemory = typeof this.instructions === "string" ? this.instructions : "";
+        const configParams = {
+            sessionId: crypto.randomUUID(),
+            targetDir: cwd,
+            cwd,
+            debugMode: options.debug ?? false,
+            model: options.model ?? PREVIEW_GEMINI_MODEL_AUTO,
+            userMemory: initialMemory,
+            enableHooks: false,
+            mcpEnabled: false,
+            extensionsEnabled: false,
+            skillsSupport: true,
+            adminSkillsEnabled: true,
+            policyEngineConfig: {
+                defaultDecision: PolicyDecision.ALLOW,
+            },
+        };
+        this.config = new Config(configParams);
+    }
+    async *sendStream(prompt, signal) {
+        await this.initialize();
+        const client = this.config.getGeminiClient();
+        const abortSignal = signal ?? new AbortController().signal;
+        const sessionId = this.config.getSessionId();
+        const agentFs = new AgentFsImpl(this.config);
+        const agentShell = new AgentShellImpl(this.config);
+        let request = [
+            { text: prompt },
+        ];
+        if (!this.instructionsLoaded) {
+            const ctx = {
+                sessionId,
+                transcript: client.getHistory(),
+                cwd: this.config.getWorkingDir(),
+                timestamp: new Date().toISOString(),
+                fs: agentFs,
+                shell: agentShell,
+                agent: this,
+            };
+            await this.resolveInstructions(ctx, client);
+        }
+        while (true) {
+            const stream = client.sendMessageStream(request, abortSignal, sessionId);
+            const events = [];
+            for await (const event of stream) {
+                yield event;
+                events.push(event);
+            }
+            const toolCalls = this.extractToolCalls(events, sessionId);
+            if (toolCalls.length === 0)
+                break;
+            const transcript = client.getHistory();
+            const ctx = {
+                sessionId,
+                transcript,
+                cwd: this.config.getWorkingDir(),
+                timestamp: new Date().toISOString(),
+                fs: agentFs,
+                shell: agentShell,
+                agent: this,
+            };
+            const scopedRegistry = this.buildScopedRegistry(ctx);
+            const completedCalls = await scheduleAgentTools(this.config, toolCalls, {
+                schedulerId: sessionId,
+                toolRegistry: scopedRegistry,
+                signal: abortSignal,
+            });
+            const functionResponses = completedCalls.flatMap((call) => call.response.responseParts);
+            request = functionResponses;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    async initialize() {
+        if (this.config.getContentGenerator())
+            return;
+        const authType = getAuthTypeFromEnv() || AuthType.COMPUTE_ADC;
+        await this.config.refreshAuth(authType);
+        await this.config.initialize();
+        // Load skills from directories
+        if (this.skillRefs.length > 0) {
+            const skillManager = this.config.getSkillManager();
+            const loadPromises = this.skillRefs.map(async (ref) => {
+                try {
+                    if (ref.type === "dir") {
+                        return await loadSkillsFromDir(ref.path);
+                    }
+                }
+                catch (e) {
+                    console.error(`Failed to load skills from ${ref.path}:`, e);
+                }
+                return [];
+            });
+            const loadedSkills = (await Promise.all(loadPromises)).flat();
+            if (loadedSkills.length > 0) {
+                skillManager.addSkills(loadedSkills);
+            }
+        }
+        // Re-register ActivateSkillTool so its schema reflects all loaded skills
+        const skillManager = this.config.getSkillManager();
+        if (skillManager.getSkills().length > 0) {
+            const registry = this.config.getToolRegistry();
+            const toolName = ActivateSkillTool.Name;
+            if (registry.getTool(toolName)) {
+                registry.unregisterTool(toolName);
+            }
+            registry.registerTool(new ActivateSkillTool(this.config, this.config.getMessageBus()));
+        }
+        // Register user-defined tools
+        const registry = this.config.getToolRegistry();
+        const messageBus = this.config.getMessageBus();
+        for (const toolDef of this.tools) {
+            const sdkTool = new SdkTool(toolDef, messageBus, this);
+            registry.registerTool(sdkTool);
+        }
+    }
+    async resolveInstructions(ctx, client) {
+        if (typeof this.instructions !== "function")
+            return;
+        const resolved = await this.instructions(ctx);
+        this.config.setUserMemory(resolved);
+        client.updateSystemInstruction();
+        this.instructionsLoaded = true;
+    }
+    buildScopedRegistry(ctx) {
+        const originalRegistry = this.config.getToolRegistry();
+        const scopedRegistry = Object.create(originalRegistry);
+        scopedRegistry.getTool = (name) => {
+            const tool = originalRegistry.getTool(name);
+            if (tool instanceof SdkTool) {
+                return tool.withContext(ctx);
+            }
+            return tool;
+        };
+        return scopedRegistry;
+    }
+    extractToolCalls(events, sessionId) {
+        const calls = [];
+        for (const event of events) {
+            if (event.type === GeminiEventType.ToolCallRequest) {
+                const toolCall = event.value;
+                const args = typeof toolCall.args === "string"
+                    ? JSON.parse(toolCall.args)
+                    : toolCall.args;
+                calls.push({
+                    ...toolCall,
+                    args,
+                    isClientInitiated: false,
+                    prompt_id: sessionId,
+                });
+            }
+        }
+        return calls;
+    }
+}

package/dist/context.d.ts

@@ -0,0 +1,41 @@
+import type { Content, Config as CoreConfig } from "@google/gemini-cli-core";
+import type { GeminiAgent } from "./agent.js";
+export interface AgentFs {
+    readFile(path: string): Promise<string | null>;
+    writeFile(path: string, content: string): Promise<void>;
+}
+export interface ShellOptions {
+    env?: Record<string, string>;
+    timeout?: number;
+    cwd?: string;
+}
+export interface ShellResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+}
+export interface AgentShell {
+    exec(cmd: string, options?: ShellOptions): Promise<ShellResult>;
+}
+export interface SessionContext {
+    sessionId: string;
+    cwd: string;
+    transcript: Content[];
+    timestamp: string;
+    fs: AgentFs;
+    shell: AgentShell;
+    agent: GeminiAgent;
+}
+export declare class AgentFsImpl implements AgentFs {
+    private readonly config;
+    constructor(config: CoreConfig);
+    readFile(path: string): Promise<string | null>;
+    writeFile(path: string, content: string): Promise<void>;
+}
+export declare class AgentShellImpl implements AgentShell {
+    private readonly config;
+    constructor(config: CoreConfig);
+    exec(command: string, options?: ShellOptions): Promise<ShellResult>;
+    private canExecute;
+}

package/dist/context.js

@@ -0,0 +1,66 @@
+import fs from "node:fs/promises";
+import { ShellExecutionService, ShellTool } from "@google/gemini-cli-core";
+// ---------------------------------------------------------------------------
+// Internal implementations (exported for use by agent.ts, not part of
+// the intended public API)
+// ---------------------------------------------------------------------------
+export class AgentFsImpl {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async readFile(path) {
+        const error = this.config.validatePathAccess(path, "read");
+        if (error)
+            return null;
+        try {
+            return await fs.readFile(path, "utf-8");
+        }
+        catch {
+            return null;
+        }
+    }
+    async writeFile(path, content) {
+        const error = this.config.validatePathAccess(path, "write");
+        if (error)
+            throw new Error(error);
+        await fs.writeFile(path, content, "utf-8");
+    }
+}
+export class AgentShellImpl {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async exec(command, options) {
+        const cwd = options?.cwd ?? this.config.getWorkingDir();
+        const abortController = new AbortController();
+        const allowed = await this.canExecute(command, cwd);
+        if (!allowed) {
+            return {
+                stdout: "",
+                stderr: "Command execution requires confirmation but no interactive session is available.",
+                exitCode: 1,
+                error: new Error("Command blocked by policy"),
+            };
+        }
+        const handle = await ShellExecutionService.execute(command, cwd, () => { }, abortController.signal, false, this.config.getShellExecutionConfig());
+        const result = await handle.result;
+        return {
+            stdout: result.output,
+            stderr: "",
+            exitCode: result.exitCode,
+        };
+    }
+    async canExecute(command, cwd) {
+        const shellTool = new ShellTool(this.config, this.config.getMessageBus());
+        try {
+            const invocation = shellTool.build({ command, dir_path: cwd });
+            const confirmation = await invocation.shouldConfirmExecute(new AbortController().signal);
+            return !confirmation;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./agent.js";
+export * from "./context.js";
+export * from "./skills.js";
+export * from "./tool.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./agent.js";
+export * from "./context.js";
+export * from "./skills.js";
+export * from "./tool.js";

package/dist/skills.d.ts

@@ -0,0 +1,8 @@
+export type SkillRef = {
+    type: "dir";
+    path: string;
+};
+/**
+ * Create a reference to a directory containing skills.
+ */
+export declare function skillDir(path: string): SkillRef;

package/dist/skills.js

@@ -0,0 +1,6 @@
+/**
+ * Create a reference to a directory containing skills.
+ */
+export function skillDir(path) {
+    return { type: "dir", path };
+}

package/dist/tool.d.ts

@@ -0,0 +1,28 @@
+import { BaseDeclarativeTool, type MessageBus, type ToolInvocation, type ToolResult } from "@google/gemini-cli-core";
+import { z } from "zod";
+import type { SessionContext } from "./context.js";
+export { z };
+export declare class ToolError extends Error {
+    constructor(message: string | Error);
+}
+export type ToolAction<T extends z.ZodTypeAny> = (params: z.infer<T>, context: SessionContext) => Promise<unknown>;
+export interface ToolDef<T extends z.ZodTypeAny> {
+    name: string;
+    description: string;
+    inputSchema: T;
+    sendErrorsToModel?: boolean;
+    action: ToolAction<T>;
+}
+export declare function defineTool<T extends z.ZodTypeAny>(config: {
+    name: string;
+    description: string;
+    inputSchema: T;
+    sendErrorsToModel?: boolean;
+}, action: ToolAction<T>): ToolDef<T>;
+export declare class SdkTool<T extends z.ZodTypeAny> extends BaseDeclarativeTool<z.infer<T>, ToolResult> {
+    private readonly def;
+    private readonly context?;
+    constructor(def: ToolDef<T>, messageBus: MessageBus, _agent?: unknown, context?: SessionContext | undefined);
+    withContext(context: SessionContext): SdkTool<T>;
+    protected createInvocation(params: z.infer<T>, messageBus: MessageBus, toolName?: string): ToolInvocation<z.infer<T>, ToolResult>;
+}

package/dist/tool.js

@@ -0,0 +1,78 @@
+import { BaseDeclarativeTool, BaseToolInvocation, Kind, } from "@google/gemini-cli-core";
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+export { z };
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+export class ToolError extends Error {
+    constructor(message) {
+        super(message instanceof Error ? message.message : message);
+        this.name = "ToolError";
+    }
+}
+export function defineTool(config, action) {
+    return {
+        name: config.name,
+        description: config.description,
+        inputSchema: config.inputSchema,
+        sendErrorsToModel: config.sendErrorsToModel,
+        action,
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal: SdkToolInvocation
+// ---------------------------------------------------------------------------
+class SdkToolInvocation extends BaseToolInvocation {
+    action;
+    context;
+    sendErrorsToModel;
+    constructor(params, messageBus, action, context, toolName, sendErrorsToModel) {
+        super(params, messageBus, toolName);
+        this.action = action;
+        this.context = context;
+        this.sendErrorsToModel = sendErrorsToModel;
+    }
+    getDescription() {
+        return `Executing ${this._toolName}...`;
+    }
+    async execute(_signal, _updateOutput) {
+        try {
+            const result = await this.action(this.params, this.context);
+            const output = this.serialize(result);
+            return { llmContent: output, returnDisplay: output };
+        }
+        catch (error) {
+            if (this.sendErrorsToModel || error instanceof ToolError) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    llmContent: `Error: ${message}`,
+                    returnDisplay: `Error: ${message}`,
+                    error: { message },
+                };
+            }
+            throw error;
+        }
+    }
+    serialize(value) {
+        return typeof value === "string" ? value : JSON.stringify(value, null, 2);
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal: SdkTool (exported for use by agent.ts)
+// ---------------------------------------------------------------------------
+export class SdkTool extends BaseDeclarativeTool {
+    def;
+    context;
+    constructor(def, messageBus, _agent, context) {
+        super(def.name, def.name, def.description, Kind.Other, zodToJsonSchema(def.inputSchema), messageBus);
+        this.def = def;
+        this.context = context;
+    }
+    withContext(context) {
+        return new SdkTool(this.def, this.messageBus, undefined, context);
+    }
+    createInvocation(params, messageBus, toolName) {
+        return new SdkToolInvocation(params, messageBus, this.def.action, this.context, toolName ?? this.name, this.def.sendErrorsToModel ?? false);
+    }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@k2wanko/gemini-cli-sdk",
+  "version": "0.1.0",
+  "description": "A lightweight SDK for building non-interactive AI agents powered by Google Gemini",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "author": "k2wanko",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/k2wanko/gemini-cli-sdk.git"
+  },
+  "homepage": "https://github.com/k2wanko/gemini-cli-sdk",
+  "bugs": {
+    "url": "https://github.com/k2wanko/gemini-cli-sdk/issues"
+  },
+  "keywords": [
+    "gemini",
+    "ai",
+    "agent",
+    "sdk",
+    "google",
+    "gemini-cli"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "biome check && tsc --noEmit",
+    "fix": "biome check --write . && tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@google/gemini-cli-core": "0.30.0-nightly.20260218.ce84b3cb5",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.23.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "latest",
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "latest"
+  }
+}