@kkeve/suite 0.0.1

package/dist/agent/factory.d.ts

@@ -0,0 +1,25 @@
+/**
+ * AgentFactory — creates execution resources for AgentLoop
+ *
+ * - Creates LLM, ToolRegistry, RuntimeEnvironment
+ * - Provides AgentLoader for agent discovery
+ * - Creates sub-agent ToolRegistry with configurable allowed/blocked tools
+ */
+import type { LLMConfig } from '../llm/types';
+import type { RuntimeEnvironment } from '../agent-loop/runtime';
+import { ToolRegistry } from '../agent-loop/types';
+import { LLM } from '../llm/index';
+import { AgentLoader } from './loader';
+export declare class AgentFactory {
+    private llm;
+    private runtime;
+    private toolRegistry;
+    private agentLoader;
+    constructor(llmConfig: LLMConfig, workspaceDir?: string);
+    init(agentsDir: string): Promise<void>;
+    getLLM(): LLM;
+    getToolRegistry(): ToolRegistry;
+    getRuntime(): RuntimeEnvironment;
+    getAgentLoader(): AgentLoader;
+    createSubAgentToolRegistry(allowedTools?: string[], blockedTools?: string[]): ToolRegistry;
+}

package/dist/agent/factory.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * AgentFactory — creates execution resources for AgentLoop
+ *
+ * - Creates LLM, ToolRegistry, RuntimeEnvironment
+ * - Provides AgentLoader for agent discovery
+ * - Creates sub-agent ToolRegistry with configurable allowed/blocked tools
+ */
+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.AgentFactory = void 0;
+const path = __importStar(require("node:path"));
+const types_1 = require("../agent-loop/types");
+const index_1 = require("../llm/index");
+const runtime_1 = require("../agent-loop/runtime");
+const index_2 = require("../tools/index");
+const loader_1 = require("./loader");
+class AgentFactory {
+    llm;
+    runtime;
+    toolRegistry;
+    agentLoader;
+    constructor(llmConfig, workspaceDir) {
+        this.llm = new index_1.LLM({
+            ...llmConfig,
+            baseURL: llmConfig.baseURL || process.env.LLM_BASE_URL || '',
+            model: llmConfig.model || process.env.LLM_MODEL_NAME || process.env.LLM_MODEL || '',
+            apiKey: llmConfig.apiKey || process.env.LLM_API_KEY || '',
+        });
+        this.runtime = (0, runtime_1.detectRuntimeEnvironment)(process.cwd(), workspaceDir || path.join(process.cwd(), 'workspace'));
+        this.toolRegistry = (0, index_2.createDefaultToolRegistry)(this.runtime);
+    }
+    async init(agentsDir) {
+        this.agentLoader = new loader_1.AgentLoader(agentsDir);
+        await this.agentLoader.discover();
+    }
+    getLLM() {
+        return this.llm;
+    }
+    getToolRegistry() {
+        return this.toolRegistry;
+    }
+    getRuntime() {
+        return this.runtime;
+    }
+    getAgentLoader() {
+        return this.agentLoader;
+    }
+    createSubAgentToolRegistry(allowedTools, blockedTools) {
+        const subRegistry = new types_1.ToolRegistry();
+        const toolFilter = (allowedTools && allowedTools.length > 0)
+            ? new Set(allowedTools)
+            : null;
+        const blocked = new Set(blockedTools ?? []);
+        for (const name of this.toolRegistry.getAllToolNames()) {
+            if (blocked.has(name))
+                continue;
+            if (toolFilter && !toolFilter.has(name))
+                continue;
+            const tool = this.toolRegistry.get(name);
+            if (tool)
+                subRegistry.register(tool);
+        }
+        return subRegistry;
+    }
+}
+exports.AgentFactory = AgentFactory;

package/dist/agent/index.d.ts

@@ -0,0 +1,3 @@
+export { AgentLoader } from './loader';
+export { AgentFactory } from './factory';
+export type { AgentRegistryDefinition } from './types';

package/dist/agent/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentFactory = exports.AgentLoader = void 0;
+var loader_1 = require("./loader");
+Object.defineProperty(exports, "AgentLoader", { enumerable: true, get: function () { return loader_1.AgentLoader; } });
+var factory_1 = require("./factory");
+Object.defineProperty(exports, "AgentFactory", { enumerable: true, get: function () { return factory_1.AgentFactory; } });

package/dist/agent/loader.d.ts

@@ -0,0 +1,22 @@
+/**
+ * AgentLoader — discovers and loads .md agent definitions from a directory
+ *
+ * Mirrors SkillLoader pattern (instance-based, no singleton).
+ * Each .md file uses YAML frontmatter (same as SKILL.md) to define agent metadata.
+ */
+import type { AgentRegistryDefinition } from './types';
+export declare class AgentLoader {
+    private agentsDir;
+    private agents;
+    constructor(agentsDir: string);
+    discover(): Promise<void>;
+    get(name: string): AgentRegistryDefinition | undefined;
+    has(name: string): boolean;
+    getAll(): Map<string, AgentRegistryDefinition>;
+    listAvailable(): Array<{
+        name: string;
+        description: string;
+        outputType?: string;
+    }>;
+    reset(): void;
+}

package/dist/agent/loader.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * AgentLoader — discovers and loads .md agent definitions from a directory
+ *
+ * Mirrors SkillLoader pattern (instance-based, no singleton).
+ * Each .md file uses YAML frontmatter (same as SKILL.md) to define agent metadata.
+ */
+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.AgentLoader = void 0;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const glob_1 = require("glob");
+const frontmatter_parser_1 = require("../skill/frontmatter-parser");
+class AgentLoader {
+    agentsDir;
+    agents = new Map();
+    constructor(agentsDir) {
+        this.agentsDir = agentsDir;
+    }
+    async discover() {
+        const absoluteDir = path.resolve(this.agentsDir);
+        try {
+            const stats = await fs.stat(absoluteDir).catch(() => null);
+            if (!stats || !stats.isDirectory()) {
+                console.warn(`[AgentLoader] Agents directory not found: ${absoluteDir}`);
+                return;
+            }
+            const agentFiles = await (0, glob_1.glob)('*.md', {
+                cwd: absoluteDir,
+                absolute: true,
+                nodir: true,
+            });
+            for (const agentFile of agentFiles) {
+                try {
+                    const content = await fs.readFile(agentFile, 'utf-8');
+                    const parsed = (0, frontmatter_parser_1.parseSkillFrontmatter)(content);
+                    if (!parsed || !parsed.name) {
+                        console.warn(`[AgentLoader] Invalid agent file: ${agentFile}`);
+                        continue;
+                    }
+                    const tools = parsed.allowedTools ?? [];
+                    const agent = {
+                        name: parsed.name,
+                        description: parsed.description,
+                        tools,
+                        outputType: parsed.outputType,
+                        model: undefined,
+                        prompt: parsed.body,
+                        location: agentFile,
+                    };
+                    this.agents.set(parsed.name, agent);
+                    console.log(`[AgentLoader] Loaded agent: "${parsed.name}" (tools: ${tools.join(', ')}, outputType: ${parsed.outputType ?? 'N/A'})`);
+                }
+                catch (err) {
+                    console.warn(`[AgentLoader] Failed to load ${agentFile}: ${err.message}`);
+                }
+            }
+            console.log(`[AgentLoader] Total agents: ${this.agents.size}`);
+        }
+        catch (err) {
+            console.warn(`[AgentLoader] Error discovering agents: ${err.message}`);
+        }
+    }
+    get(name) {
+        return this.agents.get(name);
+    }
+    has(name) {
+        return this.agents.has(name);
+    }
+    getAll() {
+        return this.agents;
+    }
+    listAvailable() {
+        return Array.from(this.agents.values()).map(a => ({
+            name: a.name,
+            description: a.description,
+            outputType: a.outputType,
+        }));
+    }
+    reset() {
+        this.agents.clear();
+    }
+}
+exports.AgentLoader = AgentLoader;

package/dist/agent/types.d.ts

@@ -0,0 +1,9 @@
+export interface AgentRegistryDefinition {
+    name: string;
+    description: string;
+    tools: string[];
+    outputType?: string;
+    model?: string;
+    prompt: string;
+    location: string;
+}

package/dist/agent/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/agent-loop/complete-task.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Complete Task Tool — signals that the agent has finished its task.
+ *
+ * Reference: gemini-cli CompleteTaskTool (tools/complete-task.ts)
+ *
+ * This tool is automatically registered in every agent loop execution.
+ * When the LLM calls this tool, the agent loop terminates with GOAL mode.
+ *
+ * The `result` parameter can be either:
+ * - A structured JSON object (when the agent has a defined output schema)
+ * - A plain string summary (for conversational tasks)
+ */
+import { z } from 'zod/v4';
+import type { ToolDefinition } from './types';
+export interface CompleteTaskToolOptions {
+    outputHint?: string;
+}
+export declare const CompleteTaskSchema: z.ZodObject<{
+    result: z.ZodAny;
+    _result: z.ZodOptional<z.ZodEnum<{
+        PASSED: "PASSED";
+        FAILED: "FAILED";
+        BLOCKED: "BLOCKED";
+    }>>;
+    _summary: z.ZodOptional<z.ZodString>;
+    _blockedReason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare function createCompleteTaskTool(options?: CompleteTaskToolOptions): ToolDefinition;

package/dist/agent-loop/complete-task.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Complete Task Tool — signals that the agent has finished its task.
+ *
+ * Reference: gemini-cli CompleteTaskTool (tools/complete-task.ts)
+ *
+ * This tool is automatically registered in every agent loop execution.
+ * When the LLM calls this tool, the agent loop terminates with GOAL mode.
+ *
+ * The `result` parameter can be either:
+ * - A structured JSON object (when the agent has a defined output schema)
+ * - A plain string summary (for conversational tasks)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompleteTaskSchema = void 0;
+exports.createCompleteTaskTool = createCompleteTaskTool;
+const v4_1 = require("zod/v4");
+const types_1 = require("./types");
+exports.CompleteTaskSchema = v4_1.z.object({
+    result: v4_1.z.any().describe('Your final result. You can provide either a structured JSON object or a text summary. ' +
+        'This is the ONLY way to finish the task — call this tool when you are done.'),
+    _result: v4_1.z.enum(['PASSED', 'FAILED', 'BLOCKED']).optional().describe('Execution result. "PASSED" = task completed successfully. ' +
+        '"FAILED" = task failed (e.g. tests did not pass). ' +
+        '"BLOCKED" = unresolved items prevent downstream steps from proceeding safely. ' +
+        'Use "BLOCKED" when critical information is missing and proceeding would produce unreliable results.'),
+    _summary: v4_1.z.string().optional().describe('Brief human-readable summary of the result (1-2 sentences). Used by the orchestrator to display progress. ' +
+        'If omitted, the orchestrator will derive a summary from the result object.'),
+    _blockedReason: v4_1.z.string().optional().describe('Reason for blocking. Required when _result is "BLOCKED". ' +
+        'Describe what information is missing and what needs to be confirmed before proceeding.'),
+});
+function createCompleteTaskTool(options) {
+    const hint = options?.outputHint;
+    const baseDescription = 'Call this tool to submit your final result and complete the task. ' +
+        'This is the ONLY way to finish. You MUST call this tool when you ' +
+        'have completed your work.';
+    const description = hint
+        ? baseDescription + '\n\n' + hint
+        : baseDescription;
+    const structuredDesc = hint
+        ? 'Structured JSON result. ' + hint
+        : 'Structured JSON result with key fields matching the expected output schema.';
+    return {
+        name: types_1.COMPLETE_TASK_TOOL_NAME,
+        description,
+        inputSchema: exports.CompleteTaskSchema,
+        execute: async (args) => {
+            const result = typeof args.result === 'string' ? args.result : args.result;
+            return { result, taskCompleted: true };
+        },
+        customJsonSchema: {
+            type: 'object',
+            properties: {
+                result: {
+                    oneOf: [
+                        {
+                            type: 'object',
+                            description: structuredDesc,
+                        },
+                        {
+                            type: 'string',
+                            description: 'Plain text summary of what you accomplished.',
+                        },
+                    ],
+                    description: 'Your final result. Provide structured JSON when a schema is defined, or a text summary otherwise.',
+                },
+            },
+            required: ['result'],
+        },
+    };
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Agent Loop module — universal agent execution engine
+ *
+ * Provides the core agent loop runtime that executes an AgentDefinition
+ * by calling the LLM in a while loop, processing tool_calls, and
+ * terminating when complete_task is called or limits are reached.
+ *
+ * Reference: gemini-cli LocalAgentExecutor (agents/local-executor.ts)
+ */
+export { AgentLoop } from './loop';
+export { createCompleteTaskTool, CompleteTaskSchema } from './complete-task';
+export type { CompleteTaskToolOptions } from './complete-task';
+export type { AgentDefinition, AgentEvent, AgentEventCallback, AgentLoopContext, AgentResult, AgentTerminateMode, ToolDefinition, ToolExecutionContext, } from './types';
+export { ToolRegistry, COMPLETE_TASK_TOOL_NAME, DEFAULT_MAX_TURNS, DEFAULT_MAX_TIME_MINUTES, } from './types';
+export { detectRuntimeEnvironment } from './runtime';
+export type { RuntimeEnvironment } from './runtime';

package/dist/agent-loop/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Agent Loop module — universal agent execution engine
+ *
+ * Provides the core agent loop runtime that executes an AgentDefinition
+ * by calling the LLM in a while loop, processing tool_calls, and
+ * terminating when complete_task is called or limits are reached.
+ *
+ * Reference: gemini-cli LocalAgentExecutor (agents/local-executor.ts)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectRuntimeEnvironment = exports.DEFAULT_MAX_TIME_MINUTES = exports.DEFAULT_MAX_TURNS = exports.COMPLETE_TASK_TOOL_NAME = exports.ToolRegistry = exports.CompleteTaskSchema = exports.createCompleteTaskTool = exports.AgentLoop = void 0;
+var loop_1 = require("./loop");
+Object.defineProperty(exports, "AgentLoop", { enumerable: true, get: function () { return loop_1.AgentLoop; } });
+var complete_task_1 = require("./complete-task");
+Object.defineProperty(exports, "createCompleteTaskTool", { enumerable: true, get: function () { return complete_task_1.createCompleteTaskTool; } });
+Object.defineProperty(exports, "CompleteTaskSchema", { enumerable: true, get: function () { return complete_task_1.CompleteTaskSchema; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "ToolRegistry", { enumerable: true, get: function () { return types_1.ToolRegistry; } });
+// Constants
+Object.defineProperty(exports, "COMPLETE_TASK_TOOL_NAME", { enumerable: true, get: function () { return types_1.COMPLETE_TASK_TOOL_NAME; } });
+Object.defineProperty(exports, "DEFAULT_MAX_TURNS", { enumerable: true, get: function () { return types_1.DEFAULT_MAX_TURNS; } });
+Object.defineProperty(exports, "DEFAULT_MAX_TIME_MINUTES", { enumerable: true, get: function () { return types_1.DEFAULT_MAX_TIME_MINUTES; } });
+// Runtime Environment
+var runtime_1 = require("./runtime");
+Object.defineProperty(exports, "detectRuntimeEnvironment", { enumerable: true, get: function () { return runtime_1.detectRuntimeEnvironment; } });

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

@@ -0,0 +1,42 @@
+/**
+ * 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
+ */
+import type { AgentDefinition, AgentEventCallback, AgentResult } from './types';
+import { ToolRegistry } from './types';
+import type { LLM } from '../llm/index';
+export declare class AgentLoop {
+    private llm;
+    private toolRegistry;
+    constructor(llm: LLM, 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)
+     */
+    execute(definition: AgentDefinition, onEvent?: AgentEventCallback, signal?: AbortSignal): Promise<AgentResult>;
+    /**
+     * Check if the agent should terminate.
+     * Returns a terminate reason if termination is needed, null otherwise.
+     */
+    private checkTermination;
+    /**
+     * Emit an event to the callback, if provided.
+     */
+    private emitEvent;
+}