@k2wanko/gemini-cli-sdk 0.3.0 → 0.5.0

package/README.md

@@ -5,6 +5,7 @@ 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

package/dist/agent.d.ts

@@ -1,4 +1,4 @@
-import { GeminiEventType, type HookDefinition, HookEventName, HookType, 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";
@@ -32,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

@@ -35,6 +35,7 @@ export class GeminiAgent {
             policyEngineConfig: {
                 defaultDecision: PolicyDecision.ALLOW,
             },
+            disableLoopDetection: true,
             compressionThreshold: options.compressionThreshold,
         };
         this.config = new Config(configParams);
@@ -43,6 +44,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/codemode.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { type ToolDef } from "./tool.js";
+export interface ExecuteResult {
+    result: unknown;
+    error?: string;
+    logs?: string[];
+}
+export interface Executor {
+    execute(code: string, fns: Record<string, (...args: unknown[]) => Promise<unknown>>): Promise<ExecuteResult>;
+}
+export declare class NodeVMExecutor implements Executor {
+    execute(code: string, fns: Record<string, (...args: unknown[]) => Promise<unknown>>): Promise<ExecuteResult>;
+}
+export declare function createCodeModeTool(options: {
+    tools: ToolDef<any>[];
+    executor?: Executor;
+    description?: string;
+}): ToolDef<z.ZodObject<{
+    code: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+}, {
+    code: string;
+}>>;

package/dist/codemode.js

@@ -0,0 +1,163 @@
+import { debugLogger } from "@google/gemini-cli-core";
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { defineTool } from "./tool.js";
+// ---------------------------------------------------------------------------
+// JSON Schema -> TypeScript type string conversion
+// ---------------------------------------------------------------------------
+function jsonSchemaToTs(schema, depth = 0) {
+    if (schema.enum) {
+        return schema.enum.map((v) => JSON.stringify(v)).join(" | ");
+    }
+    if (schema.anyOf ?? schema.oneOf) {
+        const variants = (schema.anyOf ?? schema.oneOf ?? []).map((s) => jsonSchemaToTs(s, depth));
+        return variants.join(" | ");
+    }
+    const types = Array.isArray(schema.type)
+        ? schema.type
+        : schema.type
+            ? [schema.type]
+            : [];
+    if (types.includes("string"))
+        return "string";
+    if (types.includes("number") || types.includes("integer"))
+        return "number";
+    if (types.includes("boolean"))
+        return "boolean";
+    if (types.includes("null"))
+        return "null";
+    if (types.includes("array") || schema.items) {
+        const items = schema.items
+            ? jsonSchemaToTs(schema.items, depth)
+            : "unknown";
+        return `${items}[]`;
+    }
+    if (types.includes("object") || schema.properties) {
+        const props = schema.properties ?? {};
+        const required = new Set(schema.required ?? []);
+        const indent = "  ".repeat(depth + 1);
+        const closing = "  ".repeat(depth);
+        const entries = Object.entries(props).map(([key, val]) => {
+            const opt = required.has(key) ? "" : "?";
+            const comment = val.description ? `/** ${val.description} */ ` : "";
+            return `${indent}${comment}${key}${opt}: ${jsonSchemaToTs(val, depth + 1)}`;
+        });
+        if (entries.length === 0)
+            return "Record<string, unknown>";
+        return `{\n${entries.join(";\n")};\n${closing}}`;
+    }
+    return "unknown";
+}
+// ---------------------------------------------------------------------------
+// API docs generation from ToolDef array (JSDoc-style, for LLM consumption)
+// ---------------------------------------------------------------------------
+function jsonSchemaToParams(schema, prefix = "") {
+    const props = schema.properties ?? {};
+    const required = new Set(schema.required ?? []);
+    return Object.entries(props).map(([key, val]) => {
+        const opt = required.has(key) ? "" : "?";
+        const type = jsonSchemaToTs(val);
+        const desc = val.description ? ` — ${val.description}` : "";
+        return `//   ${prefix}${key}${opt}: ${type}${desc}`;
+    });
+}
+function generateApiDocs(tools) {
+    debugLogger.debug?.("[codemode] generateApiDocs: %d tools", tools.length);
+    const sections = tools.map((tool) => {
+        const schema = zodToJsonSchema(tool.inputSchema);
+        const params = jsonSchemaToParams(schema);
+        const desc = tool.description ? ` — ${tool.description}` : "";
+        const lines = [`// codemode.${tool.name}(input)${desc}`, ...params];
+        return lines.join("\n");
+    });
+    return sections.join("\n//\n");
+}
+// ---------------------------------------------------------------------------
+// NodeVMExecutor
+// ---------------------------------------------------------------------------
+export class NodeVMExecutor {
+    async execute(code, fns) {
+        debugLogger.debug?.("[codemode:executor] execute called, code length=%d, available fns=%s", code.length, Object.keys(fns).join(", "));
+        debugLogger.debug?.("[codemode:executor] code:\n%s", code);
+        const logs = [];
+        const stringify = (v) => typeof v === "object" && v !== null ? JSON.stringify(v) : String(v);
+        const captureConsole = {
+            log: (...args) => logs.push(args.map(stringify).join(" ")),
+            warn: (...args) => logs.push(`[warn] ${args.map(stringify).join(" ")}`),
+            error: (...args) => logs.push(`[error] ${args.map(stringify).join(" ")}`),
+        };
+        try {
+            const AsyncFunction = Object.getPrototypeOf(async () => { })
+                .constructor;
+            const fn = new AsyncFunction("codemode", "console", code);
+            debugLogger.debug?.("[codemode:executor] starting execution");
+            const result = await fn(fns, captureConsole);
+            debugLogger.debug?.("[codemode:executor] execution completed, result=%s, logs=%d", typeof result, logs.length);
+            return {
+                result,
+                logs: logs.length > 0 ? logs : undefined,
+            };
+        }
+        catch (error) {
+            debugLogger.debug?.("[codemode:executor] execution failed: %s", error instanceof Error ? error.message : String(error));
+            return {
+                result: undefined,
+                error: error instanceof Error ? error.message : String(error),
+                logs: logs.length > 0 ? logs : undefined,
+            };
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// createCodeModeTool
+// ---------------------------------------------------------------------------
+export function createCodeModeTool(options) {
+    const executor = options.executor ?? new NodeVMExecutor();
+    const apiDocs = generateApiDocs(options.tools);
+    const description = options.description ??
+        `Write and execute plain JavaScript (NOT TypeScript) to orchestrate multiple tools.
+
+The \`codemode\` object exposes all available tools as async functions.
+Always end your code with a \`return\` statement to return the final result.
+
+Available tools:
+\`\`\`javascript
+${apiDocs}
+\`\`\`
+
+Example:
+\`\`\`javascript
+const result = await codemode.toolName({ param: "value" });
+return result;
+\`\`\``;
+    debugLogger.debug?.("[codemode] createCodeModeTool: registering %d tools", options.tools.length);
+    return defineTool({
+        name: "code",
+        description,
+        inputSchema: z.object({
+            code: z
+                .string()
+                .describe("JavaScript code to execute. Must use `return` to return the final result."),
+        }),
+        sendErrorsToModel: true,
+    }, async ({ code }, context) => {
+        debugLogger.debug?.("[codemode] tool invoked, code length=%d", code.length);
+        const fns = {};
+        for (const tool of options.tools) {
+            fns[tool.name] = (input) => {
+                debugLogger.debug?.("[codemode] calling tool '%s' with input: %s", tool.name, JSON.stringify(input));
+                return tool.action(input, context);
+            };
+        }
+        const execResult = await executor.execute(code, fns);
+        const output = {};
+        if (execResult.result !== undefined)
+            output.result = execResult.result;
+        if (execResult.error)
+            output.error = execResult.error;
+        if (execResult.logs && execResult.logs.length > 0)
+            output.logs = execResult.logs;
+        debugLogger.debug?.("[codemode] tool output: %s", JSON.stringify(output));
+        return output;
+    });
+}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export * from "./agent.js";
+export * from "./codemode.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,6 +1,8 @@
 export * from "./agent.js";
+export * from "./codemode.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/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.3.0",
+  "version": "0.5.0",
   "description": "A lightweight SDK for building non-interactive AI agents powered by Google Gemini",
   "type": "module",
   "private": false,
@@ -38,12 +38,13 @@
   },
   "scripts": {
     "build": "tsc",
-    "lint": "biome check && tsc --noEmit",
-    "fix": "biome check --write . && tsc --noEmit",
+    "lint": "biome check && tsc --noEmit && tsc --project tsconfig.examples.json",
+    "fix": "biome check --write . && tsc --noEmit && tsc --project tsconfig.examples.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@google/gemini-cli-core": "0.30.0-nightly.20260218.ce84b3cb5",
+    "@a2a-js/sdk": "^0.3.10",
+    "@google/gemini-cli-core": "nightly",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.1"
   },