@cleocode/adapters 2026.4.67 → 2026.4.68

package/src/providers/gemini-cli/spawn.ts

@@ -0,0 +1,220 @@
+/**
+ * Gemini CLI Spawn Provider
+ *
+ * Implements `AdapterSpawnProvider` for the Google Gemini CLI (`gemini` binary).
+ *
+ * The `gemini` binary is the Google Gemini CLI agent, available at:
+ * https://github.com/google-gemini/gemini-cli
+ *
+ * Invocation: `gemini --yolo < <prompt-file>`
+ *
+ * The provider pipes the prompt via stdin using the `--yolo` flag, which
+ * enables non-interactive mode (auto-approve all actions). Processes run
+ * detached and are tracked by PID for listing and termination.
+ *
+ * If the `gemini` binary is not found, `canSpawn()` returns `false` with a
+ * graceful error — no crash.
+ *
+ * @remarks
+ * The Gemini CLI supports a `--model` flag to select the model family and a
+ * `--yolo` flag for non-interactive headless execution (equivalent to Claude
+ * Code's `--dangerously-skip-permissions`). Prompts are supplied via stdin
+ * when run in `--yolo` mode. Install: `npm install -g @google/gemini-cli`
+ * or see the GitHub repo above.
+ *
+ * @task T648
+ */
+
+import { exec, spawn as nodeSpawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
+import { getErrorMessage } from '@cleocode/contracts';
+
+const execAsync = promisify(exec);
+
+/** Default Gemini model for subagent spawns. */
+const DEFAULT_MODEL = 'gemini-2.5-pro';
+
+/** Internal tracking entry for a spawned process. */
+interface TrackedProcess {
+  pid: number;
+  taskId: string;
+  startTime: string;
+}
+
+/**
+ * Spawn provider for the Google Gemini CLI.
+ *
+ * Spawns detached Gemini CLI processes for subagent execution. Each spawn
+ * pipes its prompt via stdin, then runs
+ * `gemini --yolo --model <model>` as a detached, unref'd child process.
+ *
+ * @remarks
+ * `canSpawn()` returns `false` (with no crash) when the `gemini` binary is
+ * not found in PATH. Install instructions are emitted via `console.warn`
+ * once to help operators discover the binary is missing.
+ *
+ * Processes are tracked by instance ID in an in-memory map and verified
+ * via `kill(pid, 0)` liveness checks.
+ *
+ * @task T648
+ */
+export class GeminiCliSpawnProvider implements AdapterSpawnProvider {
+  /** Map of instance IDs to tracked process info. */
+  private processMap = new Map<string, TrackedProcess>();
+
+  /**
+   * Check if the Gemini CLI is available in PATH.
+   *
+   * @returns `true` if `gemini` is found via `which`
+   */
+  async canSpawn(): Promise<boolean> {
+    try {
+      await execAsync('which gemini');
+      return true;
+    } catch {
+      console.warn(
+        '[GeminiCliSpawnProvider] gemini CLI not found. ' +
+          'Install: npm install -g @google/gemini-cli  ' +
+          'Docs: https://github.com/google-gemini/gemini-cli',
+      );
+      return false;
+    }
+  }
+
+  /**
+   * Spawn a subagent via the Gemini CLI.
+   *
+   * Pipes the enriched prompt to stdin and spawns a detached Gemini
+   * process. The process runs independently of the parent.
+   *
+   * @param context - Spawn context with taskId, prompt, and options
+   * @returns Spawn result with instance ID and status
+   */
+  async spawn(context: SpawnContext): Promise<SpawnResult> {
+    const instanceId = `gemini-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    const startTime = new Date().toISOString();
+
+    try {
+      // Enrich prompt with CANT bundle, memory bridge, and mental model.
+      // Best-effort: if CANT context is unavailable, the raw prompt is used.
+      let enrichedPrompt = context.prompt;
+      try {
+        const { buildCantEnrichedPrompt } = await import('../../cant-context.js');
+        enrichedPrompt = await buildCantEnrichedPrompt({
+          projectDir: context.workingDirectory ?? process.cwd(),
+          basePrompt: context.prompt,
+          agentName: (context.options?.agentName as string) ?? undefined,
+        });
+      } catch {
+        // CANT enrichment unavailable — use raw prompt
+      }
+
+      const model = (context.options?.model as string) ?? DEFAULT_MODEL;
+
+      // --yolo: non-interactive batch mode (auto-approve all actions)
+      // --model: select the Gemini model variant
+      // Prompt is supplied via stdin (pipe)
+      const args = ['--yolo', '--model', model];
+      const spawnOpts: Parameters<typeof nodeSpawn>[2] = {
+        detached: true,
+        stdio: ['pipe', 'ignore', 'ignore'],
+      };
+
+      if (context.workingDirectory) {
+        spawnOpts.cwd = context.workingDirectory;
+      }
+
+      const child = nodeSpawn('gemini', args, spawnOpts);
+
+      // Write the prompt to stdin then close so the CLI receives it.
+      if (child.stdin) {
+        child.stdin.write(enrichedPrompt, 'utf-8');
+        child.stdin.end();
+      }
+
+      child.unref();
+
+      if (child.pid) {
+        this.processMap.set(instanceId, {
+          pid: child.pid,
+          taskId: context.taskId,
+          startTime,
+        });
+      }
+
+      child.on('exit', () => {
+        this.processMap.delete(instanceId);
+      });
+
+      return {
+        instanceId,
+        taskId: context.taskId,
+        providerId: 'gemini-cli',
+        status: 'running',
+        startTime,
+      };
+    } catch (error) {
+      console.error(`[GeminiCliSpawnProvider] Failed to spawn: ${getErrorMessage(error)}`);
+
+      return {
+        instanceId,
+        taskId: context.taskId,
+        providerId: 'gemini-cli',
+        status: 'failed',
+        startTime,
+        endTime: new Date().toISOString(),
+        error: getErrorMessage(error),
+      };
+    }
+  }
+
+  /**
+   * List currently running Gemini CLI subagent processes.
+   *
+   * Checks each tracked process via kill(pid, 0) to verify it is still alive.
+   * Dead processes are automatically cleaned from the tracking map.
+   *
+   * @returns Array of spawn results for running processes
+   */
+  async listRunning(): Promise<SpawnResult[]> {
+    const running: SpawnResult[] = [];
+
+    for (const [instanceId, tracked] of this.processMap.entries()) {
+      try {
+        process.kill(tracked.pid, 0);
+        running.push({
+          instanceId,
+          taskId: tracked.taskId,
+          providerId: 'gemini-cli',
+          status: 'running',
+          startTime: tracked.startTime,
+        });
+      } catch {
+        this.processMap.delete(instanceId);
+      }
+    }
+
+    return running;
+  }
+
+  /**
+   * Terminate a running spawn by instance ID.
+   *
+   * Sends SIGTERM to the tracked process. If the process is not found
+   * or has already exited, this is a no-op.
+   *
+   * @param instanceId - ID of the spawn instance to terminate
+   */
+  async terminate(instanceId: string): Promise<void> {
+    const tracked = this.processMap.get(instanceId);
+    if (!tracked) return;
+
+    try {
+      process.kill(tracked.pid, 'SIGTERM');
+    } catch {
+      // Process may have already exited
+    }
+    this.processMap.delete(instanceId);
+  }
+}

package/src/providers/kimi/index.ts

@@ -13,6 +13,7 @@ import { KimiAdapter } from './adapter.js';
 export { KimiAdapter } from './adapter.js';
 export { KimiHookProvider } from './hooks.js';
 export { KimiInstallProvider } from './install.js';
+export { KimiSpawnProvider } from './spawn.js';
 
 export default KimiAdapter;
 

package/src/providers/kimi/spawn.ts

@@ -0,0 +1,274 @@
+/**
+ * Kimi (Moonshot AI) Spawn Provider
+ *
+ * Implements `AdapterSpawnProvider` for Moonshot AI's Kimi models.
+ *
+ * There is no widely-distributed standalone Kimi CLI binary. This provider
+ * uses the Moonshot AI Chat Completions API directly (REST, no extra SDK
+ * dependency) when `MOONSHOT_API_KEY` is present in the environment.
+ *
+ * API documentation: https://platform.moonshot.cn/docs/api/chat
+ * Endpoint: https://api.moonshot.cn/v1/chat/completions
+ *
+ * `canSpawn()` returns `true` only when:
+ * 1. `MOONSHOT_API_KEY` is set in the environment, OR
+ * 2. A `kimi` binary is found in PATH (future CLI support)
+ *
+ * If neither condition holds, `canSpawn()` returns `false` with a clear
+ * message — no crash.
+ *
+ * @remarks
+ * Unlike the CLI-based providers (codex, gemini-cli), Kimi spawn runs the
+ * API call to completion before returning (`status: 'completed'` or
+ * `status: 'failed'`). This mirrors the claude-sdk and openai-sdk providers.
+ * The API call uses Node's built-in `fetch` (Node 18+) with no extra
+ * dependencies.
+ *
+ * @task T648
+ */
+
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
+import { getErrorMessage } from '@cleocode/contracts';
+
+const execAsync = promisify(exec);
+
+/** Moonshot AI API base URL. */
+const MOONSHOT_API_BASE = 'https://api.moonshot.cn/v1';
+
+/** Default model when none is specified in spawn options. */
+const DEFAULT_MODEL = 'moonshot-v1-8k';
+
+/**
+ * Shape of a Moonshot chat completion response (subset we care about).
+ *
+ * @internal
+ */
+interface MoonshotChatResponse {
+  choices: Array<{
+    message: {
+      content: string;
+    };
+    finish_reason: string;
+  }>;
+  error?: {
+    message: string;
+    type: string;
+  };
+}
+
+/** Internal tracking entry for an in-flight API call. */
+interface TrackedRun {
+  instanceId: string;
+  taskId: string;
+  startTime: string;
+}
+
+/**
+ * Resolve the Moonshot API key from the environment.
+ *
+ * @returns The key string if set, or `null` if absent/empty.
+ */
+function resolveMoonshotApiKey(): string | null {
+  const key = process.env.MOONSHOT_API_KEY;
+  return key?.trim() ? key : null;
+}
+
+/**
+ * Check whether a `kimi` CLI binary is available in PATH.
+ *
+ * This is a forward-compatibility hook for any future official Kimi CLI.
+ *
+ * @returns `true` if `kimi` is found via `which`
+ */
+async function kimiCliBinaryAvailable(): Promise<boolean> {
+  try {
+    await execAsync('which kimi');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Spawn provider for Moonshot AI Kimi.
+ *
+ * Uses the Moonshot AI Chat Completions REST API to run subagent prompts.
+ * Each `spawn()` call completes synchronously (awaits the API response) and
+ * returns `status: 'completed'` or `status: 'failed'`.
+ *
+ * In-flight runs are tracked by instance ID so `listRunning()` reflects
+ * concurrent spawns correctly.
+ *
+ * @remarks
+ * `canSpawn()` checks for `MOONSHOT_API_KEY` first (API mode), then falls
+ * back to checking for a `kimi` CLI binary (CLI mode, future). If neither is
+ * available, `canSpawn()` returns `false` and `spawn()` throws a descriptive
+ * error rather than crashing silently.
+ *
+ * @task T648
+ */
+export class KimiSpawnProvider implements AdapterSpawnProvider {
+  /** In-flight run tracking set. */
+  private readonly runningInstances = new Map<string, TrackedRun>();
+
+  /**
+   * Check whether Kimi spawning is available in the current environment.
+   *
+   * Returns `true` when either:
+   * - `MOONSHOT_API_KEY` is set (API mode), or
+   * - A `kimi` binary is found in PATH (CLI mode — future)
+   *
+   * @returns `true` when any Kimi access method is available
+   */
+  async canSpawn(): Promise<boolean> {
+    if (resolveMoonshotApiKey()) return true;
+    if (await kimiCliBinaryAvailable()) return true;
+
+    console.warn(
+      '[KimiSpawnProvider] No Kimi access method found. ' +
+        'Set MOONSHOT_API_KEY to enable API-based spawning. ' +
+        'Get a key at: https://platform.moonshot.cn/',
+    );
+    return false;
+  }
+
+  /**
+   * Spawn a subagent via the Moonshot AI Kimi API.
+   *
+   * Enriches the prompt with CANT context (best-effort), then calls
+   * the Moonshot Chat Completions API. The call is awaited to completion.
+   *
+   * @param context - Spawn context with taskId, prompt, and options
+   * @returns Resolved spawn result with `status: 'completed'` or `'failed'`
+   */
+  async spawn(context: SpawnContext): Promise<SpawnResult> {
+    const instanceId = `kimi-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    const startTime = new Date().toISOString();
+
+    this.runningInstances.set(instanceId, {
+      instanceId,
+      taskId: context.taskId,
+      startTime,
+    });
+
+    try {
+      const apiKey = resolveMoonshotApiKey();
+      if (!apiKey) {
+        throw new Error(
+          'MOONSHOT_API_KEY is not set. ' +
+            'Set the environment variable to enable Kimi spawning. ' +
+            'Get a key at: https://platform.moonshot.cn/',
+        );
+      }
+
+      // Enrich prompt with CANT bundle, memory bridge, and mental model.
+      // Best-effort: if CANT context is unavailable, the raw prompt is used.
+      let enrichedPrompt = context.prompt;
+      try {
+        const { buildCantEnrichedPrompt } = await import('../../cant-context.js');
+        enrichedPrompt = await buildCantEnrichedPrompt({
+          projectDir: context.workingDirectory ?? process.cwd(),
+          basePrompt: context.prompt,
+          agentName: (context.options?.agentName as string) ?? undefined,
+        });
+      } catch {
+        // CANT enrichment unavailable — use raw prompt
+      }
+
+      const model = (context.options?.model as string) ?? DEFAULT_MODEL;
+
+      const response = await fetch(`${MOONSHOT_API_BASE}/chat/completions`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          model,
+          messages: [
+            {
+              role: 'user',
+              content: enrichedPrompt,
+            },
+          ],
+          stream: false,
+        }),
+      });
+
+      if (!response.ok) {
+        const bodyText = await response.text();
+        throw new Error(
+          `Moonshot API error ${response.status} ${response.statusText}: ${bodyText}`,
+        );
+      }
+
+      const data = (await response.json()) as MoonshotChatResponse;
+
+      if (data.error) {
+        throw new Error(`Moonshot API returned error: ${data.error.message} (${data.error.type})`);
+      }
+
+      const output = data.choices[0]?.message?.content ?? '';
+      const endTime = new Date().toISOString();
+      this.runningInstances.delete(instanceId);
+
+      return {
+        instanceId,
+        taskId: context.taskId,
+        providerId: 'kimi',
+        status: 'completed',
+        output,
+        exitCode: 0,
+        startTime,
+        endTime,
+      };
+    } catch (error) {
+      const endTime = new Date().toISOString();
+      this.runningInstances.delete(instanceId);
+
+      return {
+        instanceId,
+        taskId: context.taskId,
+        providerId: 'kimi',
+        status: 'failed',
+        exitCode: 1,
+        startTime,
+        endTime,
+        error: getErrorMessage(error),
+      };
+    }
+  }
+
+  /**
+   * List currently in-flight Kimi API calls.
+   *
+   * Because each `spawn()` call awaits the API response, this list is
+   * typically empty unless concurrent spawns are in flight.
+   *
+   * @returns Array of in-progress spawn results
+   */
+  async listRunning(): Promise<SpawnResult[]> {
+    return [...this.runningInstances.values()].map((entry) => ({
+      instanceId: entry.instanceId,
+      taskId: entry.taskId,
+      providerId: 'kimi',
+      status: 'running' as const,
+      startTime: entry.startTime,
+    }));
+  }
+
+  /**
+   * Remove an instance from the running-instances tracking map.
+   *
+   * The underlying fetch call cannot be cancelled externally once started.
+   * This method removes the entry so it will no longer appear in
+   * `listRunning()`, but does not abort the in-progress HTTP request.
+   *
+   * @param instanceId - ID of the spawn instance to terminate
+   */
+  async terminate(instanceId: string): Promise<void> {
+    this.runningInstances.delete(instanceId);
+  }
+}