@k2wanko/gemini-cli-sdk 0.2.1 → 0.4.0

package/README.md

@@ -5,8 +5,11 @@ Built on top of `@google/gemini-cli-core`.
 
 ## Features
 
+- **Sub-agents** — Delegate tasks to specialized child agents via `defineSubAgent()` (programmatic) or `loadSubAgents()` (markdown files), supporting both local Gemini agents and remote A2A protocol agents
 - **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
+- **Logging control** — Suppress noisy core logs by default (`"silent"`), or route them to a custom logger (pino, winston, etc.) via `logLevel` and `logger` options
+- **Hooks** — Run shell commands at lifecycle events (BeforeTool, AfterTool, BeforeAgent, etc.) to inject context, block operations, or audit tool calls — compatible with Gemini CLI's hook protocol
 
 ## Install
 

package/dist/agent.d.ts

@@ -1,8 +1,9 @@
-import { GeminiEventType, type ServerGeminiStreamEvent } from "@google/gemini-cli-core";
+import { Config, GeminiEventType, type HookDefinition, HookEventName, HookType, type ServerGeminiStreamEvent } from "@google/gemini-cli-core";
 import { type SessionContext } from "./context.js";
+import { type Logger, type LogLevel } from "./logger.js";
 import type { SkillRef } from "./skills.js";
 import { type ToolDef } from "./tool.js";
-export { GeminiEventType, type ServerGeminiStreamEvent };
+export { GeminiEventType, HookEventName, HookType, type HookDefinition, type ServerGeminiStreamEvent, };
 export interface GeminiAgentOptions {
     instructions: string | ((ctx: SessionContext) => string | Promise<string>);
     tools?: ToolDef<any>[];
@@ -14,6 +15,12 @@ export interface GeminiAgentOptions {
     sessionId?: string;
     /** Context compression threshold (0-1 fraction) */
     compressionThreshold?: number;
+    /** Core logger verbosity — default: "silent" */
+    logLevel?: LogLevel;
+    /** Custom log destination — defaults to console when logLevel is not "silent" */
+    logger?: Logger;
+    /** Hook definitions — automatically enables the hook system when provided */
+    hooks?: Partial<Record<HookEventName, HookDefinition[]>>;
 }
 export declare class GeminiAgent {
     private readonly config;
@@ -25,6 +32,12 @@ export declare class GeminiAgent {
     constructor(options: GeminiAgentOptions);
     /** Return the session ID assigned to this agent instance */
     getSessionId(): string;
+    /**
+     * Return the underlying core Config instance.
+     * Useful for advanced use cases such as sub-agent execution.
+     * The Config is lazily initialized — call after the first sendStream().
+     */
+    getCoreConfig(): Config;
     /** List available sessions for the current project */
     listSessions(): Promise<import("./session.js").SessionInfo[]>;
     sendStream(prompt: string, signal?: AbortSignal): AsyncGenerator<ServerGeminiStreamEvent>;

package/dist/agent.js

@@ -1,8 +1,9 @@
-import { ActivateSkillTool, AuthType, Config, GeminiEventType, getAuthTypeFromEnv, loadSkillsFromDir, PolicyDecision, PREVIEW_GEMINI_MODEL_AUTO, scheduleAgentTools, } from "@google/gemini-cli-core";
+import { ActivateSkillTool, AuthType, Config, GeminiEventType, getAuthTypeFromEnv, HookEventName, HookType, loadSkillsFromDir, PolicyDecision, PREVIEW_GEMINI_MODEL_AUTO, scheduleAgentTools, } from "@google/gemini-cli-core";
 import { AgentFsImpl, AgentShellImpl } from "./context.js";
+import { patchCoreLogger } from "./logger.js";
 import { listSessions, loadSession, messageRecordsToHistory, } from "./session.js";
 import { SdkTool } from "./tool.js";
-export { GeminiEventType };
+export { GeminiEventType, HookEventName, HookType, };
 export class GeminiAgent {
     config;
     tools;
@@ -11,6 +12,7 @@ export class GeminiAgent {
     resumeSessionId;
     instructionsLoaded = false;
     constructor(options) {
+        patchCoreLogger(options.logLevel ?? "silent", options.logger);
         this.instructions = options.instructions;
         this.tools = options.tools ?? [];
         this.skillRefs = options.skills ?? [];
@@ -24,7 +26,8 @@ export class GeminiAgent {
             debugMode: options.debug ?? false,
             model: options.model ?? PREVIEW_GEMINI_MODEL_AUTO,
             userMemory: initialMemory,
-            enableHooks: false,
+            enableHooks: !!options.hooks,
+            ...(options.hooks && { hooks: options.hooks }),
             mcpEnabled: false,
             extensionsEnabled: false,
             skillsSupport: true,
@@ -40,6 +43,14 @@ export class GeminiAgent {
     getSessionId() {
         return this.config.getSessionId();
     }
+    /**
+     * Return the underlying core Config instance.
+     * Useful for advanced use cases such as sub-agent execution.
+     * The Config is lazily initialized — call after the first sendStream().
+     */
+    getCoreConfig() {
+        return this.config;
+    }
     /** List available sessions for the current project */
     async listSessions() {
         await this.ensureInitialized();

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export * from "./agent.js";
 export * from "./context.js";
+export * from "./logger.js";
 export * from "./session.js";
 export * from "./skills.js";
+export * from "./subagent.js";
 export * from "./tool.js";

package/dist/index.js

@@ -1,5 +1,7 @@
 export * from "./agent.js";
 export * from "./context.js";
+export * from "./logger.js";
 export * from "./session.js";
 export * from "./skills.js";
+export * from "./subagent.js";
 export * from "./tool.js";

package/dist/logger.d.ts

@@ -0,0 +1,8 @@
+export type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+export interface Logger {
+    log?: (...args: unknown[]) => void;
+    warn?: (...args: unknown[]) => void;
+    error?: (...args: unknown[]) => void;
+    debug?: (...args: unknown[]) => void;
+}
+export declare function patchCoreLogger(level: LogLevel, logger?: Logger): void;

package/dist/logger.js

@@ -0,0 +1,21 @@
+import { debugLogger } from "@google/gemini-cli-core";
+const LOG_LEVEL_ORDER = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+};
+const noop = () => { };
+export function patchCoreLogger(level, logger) {
+    const threshold = LOG_LEVEL_ORDER[level];
+    const dest = logger ?? console;
+    debugLogger.log =
+        threshold >= LOG_LEVEL_ORDER.info ? (dest.log ?? noop).bind(dest) : noop;
+    debugLogger.warn =
+        threshold >= LOG_LEVEL_ORDER.warn ? (dest.warn ?? noop).bind(dest) : noop;
+    debugLogger.error =
+        threshold >= LOG_LEVEL_ORDER.error ? (dest.error ?? noop).bind(dest) : noop;
+    debugLogger.debug =
+        threshold >= LOG_LEVEL_ORDER.debug ? (dest.debug ?? noop).bind(dest) : noop;
+}

package/dist/subagent.d.ts

@@ -0,0 +1,58 @@
+import { AgentTerminateMode, type LocalAgentDefinition, type RemoteAgentDefinition, type SubagentActivityEvent } from "@google/gemini-cli-core";
+import { z } from "zod";
+import type { SessionContext } from "./context.js";
+import { type ToolDef } from "./tool.js";
+export { AgentTerminateMode, type SubagentActivityEvent, type LocalAgentDefinition, type RemoteAgentDefinition, };
+/**
+ * A prompt value that can be a static string or a function that dynamically
+ * resolves at invocation time. The function receives the tool input params
+ * and the parent's SessionContext.
+ *
+ * The resolved string still supports core's `${paramName}` template syntax,
+ * so both mechanisms can be combined.
+ */
+export type PromptValue<TInput extends z.ZodRawShape> = string | ((params: z.infer<z.ZodObject<TInput>>, ctx: SessionContext) => string | Promise<string>);
+export interface SubAgentOptions<TInput extends z.ZodRawShape> {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<TInput>;
+    /**
+     * System prompt — a static string or a function for dynamic resolution.
+     * Supports core's `${paramName}` template syntax (applied after resolution).
+     */
+    systemPrompt: PromptValue<TInput>;
+    /**
+     * Initial query — a static string or a function for dynamic resolution.
+     * Supports core's `${paramName}` template syntax (applied after resolution).
+     * Default: core's "Get Started!"
+     */
+    query?: PromptValue<TInput>;
+    /** Model. Default: "inherit" (parent's active model) */
+    model?: string;
+    /** Max turns. Omit to use core default. */
+    maxTurns?: number;
+    /** Max execution time in minutes. Omit to use core default. */
+    maxTimeMinutes?: number;
+    /**
+     * Tools the sub-agent can use (tool names from parent registry).
+     * Include "activate_skill" to enable skills.
+     * If omitted: inherits ALL parent tools.
+     */
+    tools?: string[];
+    /** Activity callback for observability */
+    onActivity?: (event: SubagentActivityEvent) => void;
+}
+/**
+ * Define a local sub-agent programmatically. Returns a `ToolDef` compatible
+ * with `GeminiAgent.tools`.
+ */
+export declare function defineSubAgent<TInput extends z.ZodRawShape>(options: SubAgentOptions<TInput>): ToolDef<z.ZodObject<TInput>>;
+/**
+ * Load sub-agent definitions from `.md` files in a directory.
+ * Each file becomes a `ToolDef` compatible with `GeminiAgent.tools`.
+ *
+ * Files starting with `_` are ignored by core's loader.
+ */
+export declare function loadSubAgents(dir: string, options?: {
+    onActivity?: (event: SubagentActivityEvent) => void;
+}): Promise<ToolDef<any>[]>;

package/dist/subagent.js

@@ -0,0 +1,223 @@
+import { ClientFactory } from "@a2a-js/sdk/client";
+import { AgentTerminateMode, LocalAgentExecutor, loadAgentsFromDirectory, } from "@google/gemini-cli-core";
+import { z } from "zod";
+import { ToolError } from "./tool.js";
+// ---------------------------------------------------------------------------
+// Re-exports from core
+// ---------------------------------------------------------------------------
+export { AgentTerminateMode, };
+// ---------------------------------------------------------------------------
+// defineSubAgent — Programmatic API
+// ---------------------------------------------------------------------------
+/**
+ * Define a local sub-agent programmatically. Returns a `ToolDef` compatible
+ * with `GeminiAgent.tools`.
+ */
+export function defineSubAgent(options) {
+    const hasDynamicPrompt = typeof options.systemPrompt === "function" ||
+        typeof options.query === "function";
+    // Fast path: when both prompts are static strings, build the definition
+    // upfront and delegate to the shared helper.
+    if (!hasDynamicPrompt) {
+        const def = buildLocalAgentDef(options, options.systemPrompt, options.query);
+        return wrapLocalAgentAsTool(def, options.inputSchema, options.onActivity);
+    }
+    // Dynamic path: resolve prompt values inside the action.
+    return {
+        name: options.name,
+        description: options.description,
+        inputSchema: options.inputSchema,
+        sendErrorsToModel: true,
+        action: async (params, ctx) => {
+            const resolvedSystemPrompt = await resolvePromptValue(options.systemPrompt, params, ctx);
+            const resolvedQuery = options.query !== undefined
+                ? await resolvePromptValue(options.query, params, ctx)
+                : undefined;
+            const def = buildLocalAgentDef(options, resolvedSystemPrompt, resolvedQuery);
+            return executeLocalAgent(def, params, ctx, options.onActivity);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// loadSubAgents — File-based API
+// ---------------------------------------------------------------------------
+/**
+ * Load sub-agent definitions from `.md` files in a directory.
+ * Each file becomes a `ToolDef` compatible with `GeminiAgent.tools`.
+ *
+ * Files starting with `_` are ignored by core's loader.
+ */
+export async function loadSubAgents(dir, options) {
+    const { agents, errors } = await loadAgentsFromDirectory(dir);
+    if (errors.length > 0) {
+        for (const err of errors) {
+            console.error(`[subagent] Failed to load ${err.filePath}: ${err.message}`);
+        }
+    }
+    const querySchema = z.object({
+        query: z.string().optional().describe("Input query for the sub-agent"),
+    });
+    const tools = [];
+    for (const def of agents) {
+        if (def.kind === "local") {
+            tools.push(wrapLocalAgentAsTool(def, querySchema, options?.onActivity));
+        }
+        else if (def.kind === "remote") {
+            tools.push(wrapRemoteAgentAsTool(def, querySchema));
+        }
+    }
+    return tools;
+}
+// ---------------------------------------------------------------------------
+// Internal: prompt resolution
+// ---------------------------------------------------------------------------
+async function resolvePromptValue(value, params, ctx) {
+    return typeof value === "function" ? value(params, ctx) : value;
+}
+// ---------------------------------------------------------------------------
+// Internal: build LocalAgentDefinition from SubAgentOptions + resolved strings
+// ---------------------------------------------------------------------------
+function buildLocalAgentDef(options, systemPrompt, query) {
+    return {
+        kind: "local",
+        name: options.name,
+        description: options.description,
+        inputConfig: {
+            inputSchema: zodToJsonSchemaSimple(options.inputSchema),
+        },
+        promptConfig: {
+            systemPrompt,
+            ...(query !== undefined && { query }),
+        },
+        modelConfig: { model: options.model ?? "inherit" },
+        runConfig: {
+            ...(options.maxTurns !== undefined && { maxTurns: options.maxTurns }),
+            ...(options.maxTimeMinutes !== undefined && {
+                maxTimeMinutes: options.maxTimeMinutes,
+            }),
+        },
+        ...(options.tools && { toolConfig: { tools: options.tools } }),
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal: execute a local agent (shared by wrapLocalAgentAsTool & dynamic path)
+// ---------------------------------------------------------------------------
+async function executeLocalAgent(def, params, ctx, onActivity) {
+    const config = ctx.agent.getCoreConfig();
+    // Register model config alias — replicates AgentRegistry.registerModelConfigs()
+    const alias = `${def.name}-config`;
+    config.modelConfigService.registerRuntimeModelConfig(alias, {
+        modelConfig: {
+            model: def.modelConfig.model === "inherit"
+                ? config.getActiveModel()
+                : def.modelConfig.model,
+            ...(def.modelConfig.generateContentConfig && {
+                generateContentConfig: def.modelConfig.generateContentConfig,
+            }),
+        },
+    });
+    const executor = await LocalAgentExecutor.create(def, config, onActivity);
+    const result = await executor.run(params, new AbortController().signal);
+    if (result.terminate_reason !== AgentTerminateMode.GOAL) {
+        throw new ToolError(`Sub-agent "${def.name}" terminated: ${result.terminate_reason}`);
+    }
+    return result.result;
+}
+// ---------------------------------------------------------------------------
+// Internal: wrapLocalAgentAsTool
+// ---------------------------------------------------------------------------
+function wrapLocalAgentAsTool(def, inputSchema, onActivity) {
+    return {
+        name: def.name,
+        description: def.description,
+        inputSchema,
+        sendErrorsToModel: true,
+        action: async (params, ctx) => {
+            return executeLocalAgent(def, params, ctx, onActivity);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal: wrapRemoteAgentAsTool
+// ---------------------------------------------------------------------------
+/** Cached ClientFactory instance (shared across all remote agents) */
+let sharedClientFactory;
+function getClientFactory() {
+    if (!sharedClientFactory) {
+        sharedClientFactory = new ClientFactory();
+    }
+    return sharedClientFactory;
+}
+function wrapRemoteAgentAsTool(def, inputSchema) {
+    return {
+        name: def.name,
+        description: def.description,
+        inputSchema,
+        sendErrorsToModel: true,
+        action: async (params) => {
+            const factory = getClientFactory();
+            const client = await factory.createFromUrl(def.agentCardUrl, "");
+            const query = typeof params === "object" && params !== null && "query" in params
+                ? String(params.query ?? "")
+                : JSON.stringify(params);
+            const result = await client.sendMessage({
+                message: {
+                    kind: "message",
+                    messageId: crypto.randomUUID(),
+                    role: "user",
+                    parts: [{ kind: "text", text: query }],
+                },
+                configuration: { blocking: true },
+            });
+            return extractTextFromResult(result);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal: A2A text extraction
+// ---------------------------------------------------------------------------
+function extractTextFromResult(result) {
+    if (result.kind === "message") {
+        return extractTextFromParts(result.parts);
+    }
+    // Task
+    const parts = result.status?.message?.parts;
+    if (parts) {
+        return extractTextFromParts(parts);
+    }
+    return "";
+}
+function extractTextFromParts(parts) {
+    return parts
+        .filter((p) => p.kind === "text")
+        .map((p) => p.text)
+        .join("\n");
+}
+// ---------------------------------------------------------------------------
+// Internal: minimal Zod-to-JSON-Schema for inputConfig
+// ---------------------------------------------------------------------------
+function zodToJsonSchemaSimple(schema) {
+    const shape = schema.shape;
+    const properties = {};
+    const required = [];
+    for (const [key, value] of Object.entries(shape)) {
+        const zodType = value;
+        const prop = { type: "string" };
+        if (zodType.description) {
+            prop.description = zodType.description;
+        }
+        // Unwrap optional
+        if (zodType instanceof z.ZodOptional) {
+            // optional — don't add to required
+        }
+        else {
+            required.push(key);
+        }
+        properties[key] = prop;
+    }
+    return {
+        type: "object",
+        properties,
+        ...(required.length > 0 && { required }),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2wanko/gemini-cli-sdk",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "A lightweight SDK for building non-interactive AI agents powered by Google Gemini",
   "type": "module",
   "private": false,
@@ -43,6 +43,7 @@
     "test": "bun test"
   },
   "dependencies": {
+    "@a2a-js/sdk": "^0.3.10",
     "@google/gemini-cli-core": "0.30.0-nightly.20260218.ce84b3cb5",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.1"