@kkeve/suite 0.0.1

package/dist/agent-loop/loop.js

@@ -0,0 +1,282 @@
+"use strict";
+/**
+ * Agent Loop — universal agent execution engine
+ *
+ * Reference: gemini-cli LocalAgentExecutor (agents/local-executor.ts L120-1518)
+ * Key adaptation: uses OpenAIClient.chat() instead of GeminiChat,
+ * decoupled tool execution via ToolRegistry, simplified timeout.
+ *
+ * Core loop:
+ * 1. Build messages (system prompt + user query)
+ * 2. While (!done):
+ *    a. Check termination (max turns, timeout, abort)
+ *    b. Call LLM via chatWithTools → get assistant message
+ *    c. If no tool_calls → ERROR_NO_COMPLETE_TASK (or handle text-only response)
+ *    d. For each tool_call:
+ *       - If complete_task → done, extract result
+ *       - Otherwise → execute via ToolRegistry → append tool response
+ *    e. Emit events (thought_chunk, tool_call_start/end)
+ * 3. Return AgentResult with termination mode and output
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentLoop = void 0;
+const types_1 = require("./types");
+const complete_task_1 = require("./complete-task");
+const index_1 = require("../llm/index");
+/**
+ * Universal agent execution engine.
+ *
+ * Usage:
+ * ```typescript
+ * const loop = new AgentLoop(llm, toolRegistry)
+ * const result = await loop.execute(
+ *   { name: 'my-agent', systemPrompt: '...', query: 'Do X' },
+ *   (event) => { }
+ */
+const FILE_CONTENT_TRUNCATE = 80;
+function truncateFileContent(data, toolName) {
+    if (!toolName)
+        return data;
+    const result = { ...data };
+    // 截断顶层 content（read_files 返回结果等）
+    if ((toolName === 'write_file' || toolName === 'edit_file') && typeof data.content === 'string' && data.content.length > FILE_CONTENT_TRUNCATE) {
+        result.content = data.content.slice(0, FILE_CONTENT_TRUNCATE) + `... (${data.content.length} chars)`;
+    }
+    // 截断 args.content（tool_call_start 中 write_file/edit_file 的参数）
+    if ((toolName === 'write_file' || toolName === 'edit_file') && data.args && typeof data.args.content === 'string' && data.args.content.length > FILE_CONTENT_TRUNCATE) {
+        result.args = { ...data.args };
+        result.args.content = data.args.content.slice(0, FILE_CONTENT_TRUNCATE) + `... (${data.args.content.length} chars)`;
+    }
+    if (toolName === 'read_files' && typeof data.result === 'string' && data.result.length > FILE_CONTENT_TRUNCATE) {
+        result.result = data.result.slice(0, FILE_CONTENT_TRUNCATE) + `... (${data.result.length} chars)`;
+    }
+    return result;
+}
+class AgentLoop {
+    llm;
+    toolRegistry;
+    constructor(llm, toolRegistry) {
+        this.llm = llm;
+        this.toolRegistry = toolRegistry;
+    }
+    /**
+     * Execute an agent definition with the given event callback and optional abort signal.
+     *
+     * Reference: gemini-cli LocalAgentExecutor.run() (L537-566) and runInternal() (L568-730)
+     */
+    async execute(definition, onEvent, signal) {
+        const startTime = Date.now();
+        const maxTurns = definition.maxTurns ?? types_1.DEFAULT_MAX_TURNS;
+        const maxTimeMs = (definition.maxTimeMinutes ?? types_1.DEFAULT_MAX_TIME_MINUTES) * 60 * 1000;
+        let turnCounter = 0;
+        let terminateReason = types_1.TM_ERROR;
+        let finalResult = null;
+        // 1. Build initial messages
+        const messages = [];
+        if (definition.systemPrompt) {
+            messages.push({ role: 'system', content: definition.systemPrompt });
+        }
+        const query = definition.query ?? 'Get Started!';
+        messages.push({ role: 'user', content: query });
+        // 2. Use a local tool registry copy to avoid mutating the shared one
+        const localRegistry = new types_1.ToolRegistry();
+        // Copy all tools from the shared registry
+        for (const name of this.toolRegistry.getAllToolNames()) {
+            const tool = this.toolRegistry.get(name);
+            if (tool)
+                localRegistry.register(tool);
+        }
+        // Ensure complete_task is registered (check if caller already registered one)
+        if (!localRegistry.has(types_1.COMPLETE_TASK_TOOL_NAME)) {
+            localRegistry.register((0, complete_task_1.createCompleteTaskTool)());
+        }
+        // Determine which tools are available for this agent
+        const toolsMap = definition.toolNames
+            ? localRegistry.getToolsMapSubset([...definition.toolNames, types_1.COMPLETE_TASK_TOOL_NAME])
+            : localRegistry.getToolsMap();
+        // 3. Emit start event
+        this.emitEvent(onEvent, 'agent_start', definition.name, {
+            agentName: definition.name,
+            maxTurns,
+            maxTimeMinutes: maxTimeMs / 60000,
+            toolNames: Object.keys(toolsMap),
+        });
+        // 4. Main loop (reference: gemini-cli runInternal L667-726)
+        try {
+            while (true) {
+                // 4a. Check termination conditions
+                const terminationCheck = this.checkTermination(turnCounter, maxTurns, startTime, maxTimeMs, signal);
+                if (terminationCheck) {
+                    terminateReason = terminationCheck;
+                    break;
+                }
+                // 4b. Call LLM
+                this.emitEvent(onEvent, 'thought_chunk', definition.name, {
+                    turn: turnCounter,
+                    message: `Turn ${turnCounter + 1}/${maxTurns}: Calling model...`,
+                });
+                const chatResult = await this.llm.chatWithTools(messages, toolsMap, signal);
+                // 4c. Process assistant response
+                const assistantMessage = chatResult.message;
+                messages.push(assistantMessage);
+                // 4d. Handle text-only response (no tool_calls)
+                if (!assistantMessage.tool_calls?.length) {
+                    // The LLM responded with text instead of calling any tool.
+                    // This means it didn't call complete_task → ERROR_NO_COMPLETE_TASK.
+                    // But if there's meaningful text content, we can treat it as the final result.
+                    const textContent = typeof assistantMessage.content === 'string'
+                        ? assistantMessage.content
+                        : null;
+                    if (textContent) {
+                        // The LLM gave a text answer but didn't follow the protocol.
+                        // Treat it as a soft completion.
+                        this.emitEvent(onEvent, 'thought_chunk', definition.name, {
+                            message: 'Model returned text content without calling complete_task. Treating as final answer.',
+                        });
+                        finalResult = textContent;
+                        terminateReason = types_1.TM_GOAL;
+                    }
+                    else {
+                        terminateReason = types_1.TM_ERROR_NO_COMPLETE_TASK;
+                    }
+                    break;
+                }
+                // 4e. Process each tool_call
+                let taskCompleted = false;
+                for (const toolCall of assistantMessage.tool_calls) {
+                    const toolName = toolCall.function.name;
+                    let toolArgs;
+                    try {
+                        toolArgs = JSON.parse(toolCall.function.arguments);
+                    }
+                    catch {
+                        // Handle malformed JSON (common with LLM outputs)
+                        toolArgs = {};
+                    }
+                    // Check if this is the termination signal
+                    if (toolName === types_1.COMPLETE_TASK_TOOL_NAME) {
+                        finalResult = JSON.stringify(toolArgs);
+                        taskCompleted = true;
+                        // Append tool response to messages (for history completeness)
+                        messages.push({
+                            role: 'tool',
+                            tool_call_id: toolCall.id,
+                            name: types_1.COMPLETE_TASK_TOOL_NAME,
+                            content: JSON.stringify({ result: finalResult, taskCompleted: true }),
+                        });
+                        break;
+                    }
+                    // Execute the tool via registry
+                    this.emitEvent(onEvent, 'tool_call_start', definition.name, {
+                        tool: toolName,
+                        args: toolArgs,
+                        turn: turnCounter,
+                    }, toolName);
+                    let toolResult;
+                    try {
+                        const toolContext = {
+                            runtime: globalThis.__runtime ?? {},
+                            cwd: definition.cwd ?? process.cwd(),
+                            readOnlyPaths: definition.readOnlyPaths,
+                        };
+                        toolResult = await localRegistry.execute(toolName, toolArgs, toolContext);
+                    }
+                    catch (error) {
+                        toolResult = { error: error.message || String(error), isError: true };
+                        this.emitEvent(onEvent, 'agent_error', definition.name, {
+                            tool: toolName,
+                            error: error.message,
+                        });
+                    }
+                    this.emitEvent(onEvent, 'tool_call_end', definition.name, {
+                        tool: toolName,
+                        result: typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult),
+                        turn: turnCounter,
+                    }, toolName);
+                    // Append tool response to messages
+                    messages.push({
+                        role: 'tool',
+                        tool_call_id: toolCall.id,
+                        name: toolName,
+                        content: typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult),
+                    });
+                }
+                if (taskCompleted) {
+                    terminateReason = types_1.TM_GOAL;
+                    break;
+                }
+                turnCounter++;
+            }
+        }
+        catch (error) {
+            // Check if it's an abort error
+            if (error?.name === 'AbortError' || signal?.aborted) {
+                terminateReason = types_1.TM_ABORTED;
+            }
+            else {
+                terminateReason = types_1.TM_ERROR;
+                finalResult = null;
+                // Enhanced error logging for debugging
+                const errorDetail = error instanceof index_1.InvokeError
+                    ? `[InvokeError type=${error.type} retryable=${error.retryable}] ${error.message}`
+                    : error?.message || String(error);
+                console.error(`[AgentLoop] Agent "${definition.name}" terminated with ERROR: ${errorDetail}`);
+                if (error instanceof index_1.InvokeError && error.rawResponse) {
+                    console.error(`[AgentLoop] InvokeError rawResponse:`, JSON.stringify(error.rawResponse).slice(0, 500));
+                }
+                this.emitEvent(onEvent, 'agent_error', definition.name, {
+                    error: errorDetail,
+                    errorType: error?.type || error?.constructor?.name || 'unknown',
+                    phase: 'execution',
+                    turn: turnCounter,
+                });
+            }
+        }
+        // 5. Emit end event
+        this.emitEvent(onEvent, 'agent_end', definition.name, {
+            terminateReason,
+            turnCount: turnCounter,
+            durationMs: Date.now() - startTime,
+            output: finalResult ?? undefined,
+        });
+        // 6. Return result
+        return {
+            success: terminateReason === types_1.TM_GOAL,
+            output: finalResult ?? undefined,
+            terminateReason,
+            turnCount: turnCounter,
+            durationMs: Date.now() - startTime,
+            error: terminateReason !== types_1.TM_GOAL
+                ? `Agent terminated: ${terminateReason}${terminateReason === types_1.TM_ERROR_NO_COMPLETE_TASK ? ' (model stopped calling tools without complete_task)' : ''}`
+                : undefined,
+        };
+    }
+    /**
+     * Check if the agent should terminate.
+     * Returns a terminate reason if termination is needed, null otherwise.
+     */
+    checkTermination(turnCounter, maxTurns, startTime, maxTimeMs, signal) {
+        if (turnCounter >= maxTurns) {
+            return types_1.TM_MAX_TURNS;
+        }
+        if (signal?.aborted) {
+            return types_1.TM_ABORTED;
+        }
+        if (Date.now() - startTime >= maxTimeMs) {
+            return types_1.TM_TIMEOUT;
+        }
+        return null;
+    }
+    /**
+     * Emit an event to the callback, if provided.
+     */
+    emitEvent(onEvent, type, streamId, data, toolName) {
+        if (onEvent) {
+            const processed = (type === 'tool_call_start' || type === 'tool_call_end')
+                ? truncateFileContent(data, toolName)
+                : data;
+            onEvent({ type, streamId, data: processed });
+        }
+    }
+}
+exports.AgentLoop = AgentLoop;

package/dist/agent-loop/runtime.d.ts

@@ -0,0 +1,40 @@
+/**
+ * RuntimeEnvironment — runtime environment detection
+ *
+ * Detects available system binaries (git/codegraph/playwright/node),
+ * and provides config paths (env).
+ *
+ * Tools (core/tools/*) get paths via ToolExecutionContext.runtime,
+ * instead of resolving binaries themselves.
+ *
+ * Design decisions:
+ * D02: Layer 1: RuntimeEnvironment provides binary paths
+ *      Layer 2: Tool execute() gets paths from runtime
+ *      Layer 3: Skill only ctx.tools.call(), no path awareness
+ * D04: Business-specific paths (keveWikiDir/reposBaseDir) removed from core.
+ *      Agent package can add them in its own runtime extension.
+ */
+export interface RuntimeEnvironment {
+    /** Git binary path */
+    gitBin: string;
+    /** Codegraph binary path */
+    codegraphBin: string;
+    /** Playwright binary path (usually in agent's node_modules/.bin) */
+    playwrightBin: string;
+    /** Node binary path */
+    nodeBin: string;
+    /** Package manager (pnpm/npm/yarn) */
+    packageManager: string;
+    /** Environment variables (tokens, configs) */
+    env: Record<string, string>;
+}
+/**
+ * Detect the runtime environment.
+ *
+ * Scans for binaries, loads env vars.
+ * Called once at startup (entry.ts) and passed to Pipeline → SkillContext.
+ *
+ * @param cwd - Starting directory (defaults to process.cwd())
+ * @param agentDir - Agent package directory for finding node_modules binaries
+ */
+export declare function detectRuntimeEnvironment(cwd?: string, agentDir?: string): RuntimeEnvironment;

package/dist/agent-loop/runtime.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * RuntimeEnvironment — runtime environment detection
+ *
+ * Detects available system binaries (git/codegraph/playwright/node),
+ * and provides config paths (env).
+ *
+ * Tools (core/tools/*) get paths via ToolExecutionContext.runtime,
+ * instead of resolving binaries themselves.
+ *
+ * Design decisions:
+ * D02: Layer 1: RuntimeEnvironment provides binary paths
+ *      Layer 2: Tool execute() gets paths from runtime
+ *      Layer 3: Skill only ctx.tools.call(), no path awareness
+ * D04: Business-specific paths (keveWikiDir/reposBaseDir) removed from core.
+ *      Agent package can add them in its own runtime extension.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectRuntimeEnvironment = detectRuntimeEnvironment;
+const path = __importStar(require("node:path"));
+const fs = __importStar(require("node:fs"));
+const node_child_process_1 = require("node:child_process");
+// ===== Detection =====
+/**
+ * Find a binary on the system PATH.
+ * Returns the absolute path or the binary name if not found (will fail at exec time).
+ */
+function findBinary(name) {
+    try {
+        return (0, node_child_process_1.execSync)(`which ${name} 2>/dev/null`, { encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return name;
+    }
+}
+/**
+ * Detect package manager from lockfile
+ */
+function detectPackageManager(projectDir) {
+    if (fs.existsSync(path.join(projectDir, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (fs.existsSync(path.join(projectDir, 'yarn.lock')))
+        return 'yarn';
+    if (fs.existsSync(path.join(projectDir, 'package-lock.json')))
+        return 'npm';
+    return 'pnpm';
+}
+/**
+ * Load environment variables from .env file (if present)
+ */
+function loadEnvFile(envPath) {
+    const env = {};
+    if (!fs.existsSync(envPath))
+        return env;
+    try {
+        const content = fs.readFileSync(envPath, 'utf-8');
+        for (const line of content.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#'))
+                continue;
+            const eqIndex = trimmed.indexOf('=');
+            if (eqIndex > 0) {
+                const key = trimmed.slice(0, eqIndex).trim();
+                let value = trimmed.slice(eqIndex + 1).trim();
+                if ((value.startsWith('"') && value.endsWith('"')) ||
+                    (value.startsWith("'") && value.endsWith("'"))) {
+                    value = value.slice(1, -1);
+                }
+                env[key] = value;
+            }
+        }
+    }
+    catch {
+        // Ignore .env read errors
+    }
+    return env;
+}
+/**
+ * Detect the runtime environment.
+ *
+ * Scans for binaries, loads env vars.
+ * Called once at startup (entry.ts) and passed to Pipeline → SkillContext.
+ *
+ * @param cwd - Starting directory (defaults to process.cwd())
+ * @param agentDir - Agent package directory for finding node_modules binaries
+ */
+function detectRuntimeEnvironment(cwd, agentDir) {
+    const startDir = cwd ?? process.cwd();
+    const pkgDir = agentDir ?? findPkgDir(startDir);
+    // Find playwright binary: prefer agent's node_modules, fallback to global
+    const localPlaywright = path.join(pkgDir, 'node_modules', '.bin', 'playwright');
+    const playwrightBin = fs.existsSync(localPlaywright)
+        ? localPlaywright
+        : findBinary('playwright');
+    // Load .env from agent/pkg dir
+    const env = {
+        ...loadEnvFile(path.join(pkgDir, '.env')),
+    };
+    // Also inherit relevant process.env
+    for (const key of ['GITLAB_TOKEN', 'HOME', 'PATH', 'NODE_ENV']) {
+        if (process.env[key])
+            env[key] = process.env[key];
+    }
+    return {
+        gitBin: findBinary('git'),
+        codegraphBin: findBinary('codegraph'),
+        playwrightBin,
+        nodeBin: process.execPath,
+        packageManager: detectPackageManager(pkgDir),
+        env,
+    };
+}
+/**
+ * Walk up from startDir to find the nearest package directory
+ * (contains package.json with node_modules)
+ */
+function findPkgDir(startDir) {
+    let dir = startDir;
+    for (let i = 0; i < 15; i++) {
+        const pkgPath = path.join(dir, 'package.json');
+        if (fs.existsSync(pkgPath) && fs.existsSync(path.join(dir, 'node_modules'))) {
+            return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return startDir;
+}

package/dist/agent-loop/types.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Agent Loop Core Types
+ *
+ * Reference: gemini-cli LocalAgentExecutor + AgentProtocol
+ * Adapted for OpenAI-compatible API (internal proxy at xxx)
+ *
+ * Key differences from gemini-cli:
+ * - LLM calls use OpenAIClient instead of GeminiChat
+ * - Tool definitions reuse core/llm/types.ts Tool interface
+ * - No Gemini-specific Content/Part types — use OpenAI Message format
+ * - Simplified timeout (no DeadlineTimer pause/resume — we don't wait for user confirmation)
+ */
+import type { LLMClient, Tool } from '../llm/types';
+import type { RuntimeEnvironment } from './runtime';
+/** Default maximum number of conversational turns for an agent. */
+export declare const DEFAULT_MAX_TURNS = 30;
+/** Default maximum execution time for an agent in minutes. */
+export declare const DEFAULT_MAX_TIME_MINUTES = 10;
+/** Tool name for signaling task completion (reference: gemini-cli CompleteTaskTool) */
+export declare const COMPLETE_TASK_TOOL_NAME = "complete_task";
+/**
+ * Definition of an agent to execute via the loop.
+ * Reference: gemini-cli LocalAgentDefinition (agents/types.ts L214-285)
+ *
+ * Simplified from gemini-cli: removed kind, promptConfig, modelConfig, runConfig,
+ * workspaceDirectories, memoryInboxAccess, mcpServers, processOutput, onBeforeTurn.
+ * These features can be added incrementally as needed.
+ */
+export interface AgentDefinition {
+    /** Unique identifier for the agent. */
+    name: string;
+    /** Human-readable description. */
+    description: string;
+    /** System prompt injected as the first message. Can include SKILL.md content. */
+    systemPrompt?: string;
+    /** The initial user query/message. Defaults to 'Get Started!' if not provided. */
+    query?: string;
+    /** Maximum number of conversational turns. Defaults to DEFAULT_MAX_TURNS (30). */
+    maxTurns?: number;
+    /** Maximum execution time in minutes. Defaults to DEFAULT_MAX_TIME_MINUTES (10). */
+    maxTimeMinutes?: number;
+    /** Tool names to restrict to. If omitted, all registered tools are available. */
+    toolNames?: string[];
+    /** Paths that are read-only — bash tool will block write operations targeting these directories */
+    readOnlyPaths?: string[];
+    /** Working directory for tool execution. Defaults to process.cwd() */
+    cwd?: string;
+}
+/**
+ * Execution context for the agent loop.
+ * Provides the LLM client, tool registry, and config needed to run an agent.
+ */
+export interface AgentLoopContext {
+    /** LLM client for calling the model. Uses core/llm/OpenAIClient. */
+    llmClient: LLMClient;
+    /** Tool registry for executing tool calls from the model. */
+    toolRegistry: ToolRegistry;
+    /** Application configuration. */
+    config: Record<string, unknown>;
+}
+/**
+ * Callback for receiving agent events during execution.
+ * Events are emitted at key points: start, tool calls, thoughts, end, errors.
+ */
+export type AgentEventCallback = (event: AgentEvent) => void;
+/**
+ * Events emitted during agent execution.
+ * Reference: gemini-cli AgentEvents (agent/types.ts L104-131) and SubagentActivityEvent (agents/types.ts L84-89)
+ *
+ * Simplified from gemini-cli: merged multiple event interfaces into one,
+ * removed display-specific fields (DisplayContent, ToolDisplayFormat).
+ */
+export interface AgentEvent {
+    type: 'agent_start' | 'tool_call_start' | 'tool_call_end' | 'thought_chunk' | 'agent_end' | 'agent_error';
+    /** Stream identifier (typically the agent name). */
+    streamId: string;
+    /** Event-specific data. */
+    data: Record<string, unknown>;
+}
+/**
+ * Describes how an agent's execution ended.
+ * Reference: gemini-cli AgentTerminateMode (agents/types.ts L24-31)
+ */
+export declare const TM_GOAL = "GOAL";
+export declare const TM_TIMEOUT = "TIMEOUT";
+export declare const TM_MAX_TURNS = "MAX_TURNS";
+export declare const TM_ABORTED = "ABORTED";
+export declare const TM_ERROR = "ERROR";
+export declare const TM_ERROR_NO_COMPLETE_TASK = "ERROR_NO_COMPLETE_TASK";
+export type AgentTerminateMode = typeof TM_GOAL | typeof TM_TIMEOUT | typeof TM_MAX_TURNS | typeof TM_ABORTED | typeof TM_ERROR | typeof TM_ERROR_NO_COMPLETE_TASK;
+/**
+ * The final result of an agent's execution.
+ * Reference: gemini-cli OutputObject (agents/types.ts L36-41)
+ */
+export interface AgentResult {
+    /** Whether the agent completed successfully (GOAL termination). */
+    success: boolean;
+    /** The final output string from complete_task, if available. */
+    output?: string;
+    /** How the agent's execution ended. */
+    terminateReason: AgentTerminateMode;
+    /** Number of conversational turns completed. */
+    turnCount: number;
+    /** Total execution time in milliseconds. */
+    durationMs: number;
+    /** Error message if the agent failed. */
+    error?: string;
+}
+export interface ToolExecutionContext {
+    /** Runtime environment (binary paths, config dirs, env vars) */
+    runtime: RuntimeEnvironment;
+    /** Working directory for command execution */
+    cwd: string;
+    /** Timeout in milliseconds */
+    timeout?: number;
+    /** 🆕 Paths that are read-only — bash tool will block write operations to these directories */
+    readOnlyPaths?: string[];
+}
+/**
+ * A tool definition for the agent loop's registry.
+ * Compatible with core/llm/types.ts Tool interface.
+ */
+export interface ToolDefinition {
+    /** Tool name (used as the key in OpenAI function_call). */
+    name: string;
+    /** Human-readable description sent to the LLM. */
+    description: string;
+    /** Zod schema for input validation and OpenAI parameter generation. */
+    inputSchema: z.ZodType<any>;
+    /** Execute the tool with validated arguments. */
+    execute: (args: any, context?: ToolExecutionContext) => Promise<any>;
+    /** Custom JSON Schema for the LLM (overrides zod conversion). */
+    customJsonSchema?: Record<string, any>;
+}
+import type * as z from 'zod/v4';
+/**
+ * Tool registry for managing and executing tools during agent execution.
+ * Reference: gemini-cli ToolRegistry (tools/tool-registry.ts)
+ *
+ * Simplified: no message bus, no confirmation policy, no sort, no MCP integration.
+ * These can be added incrementally.
+ */
+export declare class ToolRegistry {
+    private tools;
+    /** Register a tool definition. */
+    register(tool: ToolDefinition): void;
+    /** Unregister a tool by name. */
+    unregister(name: string): void;
+    /** Get all registered tool names. */
+    getAllToolNames(): string[];
+    /** Convert registered tools to the core/llm/types.ts Tool map format for LLM calls. */
+    getToolsMap(): Record<string, Tool>;
+    /** Get a subset of tools by name (for agent's toolNames restriction). */
+    getToolsMapSubset(names: string[]): Record<string, Tool>;
+    /** Execute a registered tool by name with the given arguments and optional context. */
+    execute(name: string, args: any, context?: ToolExecutionContext): Promise<any>;
+    /** Check if a tool is registered. */
+    has(name: string): boolean;
+    /** Get a tool definition by name. */
+    get(name: string): ToolDefinition | undefined;
+}