@kkeve/suite 0.0.1 → 0.0.2

package/dist/index.d.ts

@@ -1,23 +1,8 @@
-/**
- * Core module — runtime infrastructure for the agent
- *
- * Layers:
- * - llm/     — OpenAI-compatible LLM client (invoke + chat)
- * - context/ — Token calculation + truncation (from gemini-cli)
- * - agent-loop/ — Universal agent execution engine (while loop + LLM + tools)
- * - skill/   — SKILL.md discovery, loading, and execution (Progressive Disclosure)
- * - tools/   — Built-in tool library (bash, codegraph, git, keve-read-doc, etc.)
- */
-export { LLM, InvokeError, InvokeErrorType } from './llm/index';
-export type { ChatResult, ContentItem, InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool, } from './llm/index';
-export { estimateCharsFromTokens, truncateProportionally, normalizeFunctionResponse, estimateTokenCountSync, } from './context/index';
-export type { TokenEstimationPart } from './context/index';
-export { AgentLoop } from './agent-loop/index';
-export type { AgentDefinition, AgentEvent, AgentEventCallback, AgentLoopContext, AgentResult, AgentTerminateMode, ToolDefinition, } from './agent-loop/index';
-export { COMPLETE_TASK_TOOL_NAME, DEFAULT_MAX_TURNS, DEFAULT_MAX_TIME_MINUTES, createCompleteTaskTool, ToolRegistry, detectRuntimeEnvironment, } from './agent-loop/index';
-export type { RuntimeEnvironment, ToolExecutionContext, CompleteTaskToolOptions } from './agent-loop/index';
-export { AgentLoader, AgentFactory } from './agent/index';
-export type { AgentRegistryDefinition } from './agent/index';
-export { SkillLoader } from './skill/index';
-export type { SkillDefinition } from './skill/index';
-export { createDefaultToolRegistry, getBuiltinToolNames } from './tools/index';
+export { generateReportData, type ReportDataOptions, parseCaseIdFromTitle, extractAllSpecs, buildCaseResultMap, parseYamlSimple } from './core/generateReport/reportData';
+export { KevePageAgent, reactLoop, type AgentResult, type AgentStepEvent, type AgentEvent, type AgentOptions, type AgentHooks } from './page-agent/agent';
+export { tools, packMacroToolSchema, type PageAgentTool, type MacroToolInput, type ToolContext } from './page-agent/tools';
+export { keveAspect, KeveAspectRegistry, type AspectPhase, type AspectDefinition, type GoalContext, type GoalResult } from './core/keve-aspect';
+export { ActionLogWriter, type ActionLogRecord } from './core/action-log-writer';
+export { learnedActions, LearnedActions } from './core/learned-actions';
+export { generatePwConfig, resolveConfigOutputPath, findExistingConfig, type PwConfigOptions } from './core/pw-config';
+export { run, KeveRunError, type RunOptions, type RunResult } from './commands/run';

package/dist/index.js

@@ -1,45 +1,38 @@
 "use strict";
-/**
- * Core module — runtime infrastructure for the agent
- *
- * Layers:
- * - llm/     — OpenAI-compatible LLM client (invoke + chat)
- * - context/ — Token calculation + truncation (from gemini-cli)
- * - agent-loop/ — Universal agent execution engine (while loop + LLM + tools)
- * - skill/   — SKILL.md discovery, loading, and execution (Progressive Disclosure)
- * - tools/   — Built-in tool library (bash, codegraph, git, keve-read-doc, etc.)
- */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getBuiltinToolNames = exports.createDefaultToolRegistry = exports.SkillLoader = exports.AgentFactory = exports.AgentLoader = exports.detectRuntimeEnvironment = exports.ToolRegistry = exports.createCompleteTaskTool = exports.DEFAULT_MAX_TIME_MINUTES = exports.DEFAULT_MAX_TURNS = exports.COMPLETE_TASK_TOOL_NAME = exports.AgentLoop = exports.estimateTokenCountSync = exports.normalizeFunctionResponse = exports.truncateProportionally = exports.estimateCharsFromTokens = exports.InvokeErrorType = exports.InvokeError = exports.LLM = void 0;
-// LLM
-var index_1 = require("./llm/index");
-Object.defineProperty(exports, "LLM", { enumerable: true, get: function () { return index_1.LLM; } });
-Object.defineProperty(exports, "InvokeError", { enumerable: true, get: function () { return index_1.InvokeError; } });
-Object.defineProperty(exports, "InvokeErrorType", { enumerable: true, get: function () { return index_1.InvokeErrorType; } });
-// Context
-var index_2 = require("./context/index");
-Object.defineProperty(exports, "estimateCharsFromTokens", { enumerable: true, get: function () { return index_2.estimateCharsFromTokens; } });
-Object.defineProperty(exports, "truncateProportionally", { enumerable: true, get: function () { return index_2.truncateProportionally; } });
-Object.defineProperty(exports, "normalizeFunctionResponse", { enumerable: true, get: function () { return index_2.normalizeFunctionResponse; } });
-Object.defineProperty(exports, "estimateTokenCountSync", { enumerable: true, get: function () { return index_2.estimateTokenCountSync; } });
-// Agent Loop
-var index_3 = require("./agent-loop/index");
-Object.defineProperty(exports, "AgentLoop", { enumerable: true, get: function () { return index_3.AgentLoop; } });
-var index_4 = require("./agent-loop/index");
-Object.defineProperty(exports, "COMPLETE_TASK_TOOL_NAME", { enumerable: true, get: function () { return index_4.COMPLETE_TASK_TOOL_NAME; } });
-Object.defineProperty(exports, "DEFAULT_MAX_TURNS", { enumerable: true, get: function () { return index_4.DEFAULT_MAX_TURNS; } });
-Object.defineProperty(exports, "DEFAULT_MAX_TIME_MINUTES", { enumerable: true, get: function () { return index_4.DEFAULT_MAX_TIME_MINUTES; } });
-Object.defineProperty(exports, "createCompleteTaskTool", { enumerable: true, get: function () { return index_4.createCompleteTaskTool; } });
-Object.defineProperty(exports, "ToolRegistry", { enumerable: true, get: function () { return index_4.ToolRegistry; } });
-Object.defineProperty(exports, "detectRuntimeEnvironment", { enumerable: true, get: function () { return index_4.detectRuntimeEnvironment; } });
-// Agent
-var index_5 = require("./agent/index");
-Object.defineProperty(exports, "AgentLoader", { enumerable: true, get: function () { return index_5.AgentLoader; } });
-Object.defineProperty(exports, "AgentFactory", { enumerable: true, get: function () { return index_5.AgentFactory; } });
-// Skill
-var index_6 = require("./skill/index");
-Object.defineProperty(exports, "SkillLoader", { enumerable: true, get: function () { return index_6.SkillLoader; } });
-// Tools (general tools, aligned with gemini-cli)
-var index_7 = require("./tools/index");
-Object.defineProperty(exports, "createDefaultToolRegistry", { enumerable: true, get: function () { return index_7.createDefaultToolRegistry; } });
-Object.defineProperty(exports, "getBuiltinToolNames", { enumerable: true, get: function () { return index_7.getBuiltinToolNames; } });
+exports.KeveRunError = exports.run = exports.findExistingConfig = exports.resolveConfigOutputPath = exports.generatePwConfig = exports.LearnedActions = exports.learnedActions = exports.ActionLogWriter = exports.KeveAspectRegistry = exports.keveAspect = exports.packMacroToolSchema = exports.tools = exports.reactLoop = exports.KevePageAgent = exports.parseYamlSimple = exports.buildCaseResultMap = exports.extractAllSpecs = exports.parseCaseIdFromTitle = exports.generateReportData = void 0;
+var reportData_1 = require("./core/generateReport/reportData");
+Object.defineProperty(exports, "generateReportData", { enumerable: true, get: function () { return reportData_1.generateReportData; } });
+Object.defineProperty(exports, "parseCaseIdFromTitle", { enumerable: true, get: function () { return reportData_1.parseCaseIdFromTitle; } });
+Object.defineProperty(exports, "extractAllSpecs", { enumerable: true, get: function () { return reportData_1.extractAllSpecs; } });
+Object.defineProperty(exports, "buildCaseResultMap", { enumerable: true, get: function () { return reportData_1.buildCaseResultMap; } });
+Object.defineProperty(exports, "parseYamlSimple", { enumerable: true, get: function () { return reportData_1.parseYamlSimple; } });
+// Re-Act loop (refactored to page-agent)
+var agent_1 = require("./page-agent/agent");
+Object.defineProperty(exports, "KevePageAgent", { enumerable: true, get: function () { return agent_1.KevePageAgent; } });
+Object.defineProperty(exports, "reactLoop", { enumerable: true, get: function () { return agent_1.reactLoop; } });
+var tools_1 = require("./page-agent/tools");
+Object.defineProperty(exports, "tools", { enumerable: true, get: function () { return tools_1.tools; } });
+Object.defineProperty(exports, "packMacroToolSchema", { enumerable: true, get: function () { return tools_1.packMacroToolSchema; } });
+// Aspect registry (new)
+var keve_aspect_1 = require("./core/keve-aspect");
+Object.defineProperty(exports, "keveAspect", { enumerable: true, get: function () { return keve_aspect_1.keveAspect; } });
+Object.defineProperty(exports, "KeveAspectRegistry", { enumerable: true, get: function () { return keve_aspect_1.KeveAspectRegistry; } });
+// Action log (new)
+var action_log_writer_1 = require("./core/action-log-writer");
+Object.defineProperty(exports, "ActionLogWriter", { enumerable: true, get: function () { return action_log_writer_1.ActionLogWriter; } });
+// Learned actions (new)
+var learned_actions_1 = require("./core/learned-actions");
+Object.defineProperty(exports, "learnedActions", { enumerable: true, get: function () { return learned_actions_1.learnedActions; } });
+Object.defineProperty(exports, "LearnedActions", { enumerable: true, get: function () { return learned_actions_1.LearnedActions; } });
+// Playwright config generator
+var pw_config_1 = require("./core/pw-config");
+Object.defineProperty(exports, "generatePwConfig", { enumerable: true, get: function () { return pw_config_1.generatePwConfig; } });
+Object.defineProperty(exports, "resolveConfigOutputPath", { enumerable: true, get: function () { return pw_config_1.resolveConfigOutputPath; } });
+Object.defineProperty(exports, "findExistingConfig", { enumerable: true, get: function () { return pw_config_1.findExistingConfig; } });
+// Run API
+var run_1 = require("./commands/run");
+Object.defineProperty(exports, "run", { enumerable: true, get: function () { return run_1.run; } });
+Object.defineProperty(exports, "KeveRunError", { enumerable: true, get: function () { return run_1.KeveRunError; } });
+// Script refine (new)
+// script-refine is now part of page-agent/tools

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

@@ -0,0 +1,129 @@
+/**
+ * page-agent/agent.ts — KevePageAgent
+ *
+ * Re-Act agent for E2E test goal exploration.
+ * Refactored from react-loop.ts to follow PageAgentCore patterns:
+ *   - MacroTool: merge all tool schemas into one LLM output
+ *   - History events: step/observation/error stream
+ *   - Reflection-before-action: evaluation + memory + next_goal + action
+ *   - Screenshot injected into LLM prompt as multimodal input — LLM self-evaluates visually
+ *   - No external verification — LLM sees screenshot each step, judges goal state itself
+ *
+ * Usage:
+ *   const agent = new KevePageAgent(page, { maxSteps: 5 });
+ *   const result = await agent.execute(step, expected, { learnedActionsHint, fnResult });
+ */
+import type { Page } from '@playwright/test';
+import { LLM } from '@ks-data/keve-core/llm';
+export interface AgentStepEvent {
+    type: 'step';
+    stepIndex: number;
+    evaluation: string;
+    memory: string;
+    nextGoal: string;
+    toolName: string;
+    toolInput: any;
+    toolOutput: string;
+    toolError?: string;
+    snapshot: string;
+    screenshotPath?: string;
+}
+export interface AgentObservationEvent {
+    type: 'observation';
+    content: string;
+}
+export interface AgentErrorEvent {
+    type: 'error';
+    message: string;
+}
+export type AgentEvent = AgentStepEvent | AgentObservationEvent | AgentErrorEvent;
+export interface AgentResult {
+    success: boolean;
+    data: string;
+    events: AgentEvent[];
+    finalSnapshot: string;
+    agentScreenshots?: string[];
+    diagnosticHints?: string[];
+}
+export interface AgentHooks {
+    /** Called before task execution starts. */
+    onBeforeTask?: (agent: KevePageAgent) => Promise<void> | void;
+    /** Called after task execution completes. Return partial result to override fields. */
+    onAfterTask?: (agent: KevePageAgent, result: AgentResult) => Promise<Partial<AgentResult> | void> | Partial<AgentResult> | void;
+    /** Called before each step execution. */
+    onBeforeStep?: (agent: KevePageAgent, stepCount: number) => Promise<void> | void;
+    /** Called after each step execution (in finally block). */
+    onAfterStep?: (agent: KevePageAgent, events: AgentEvent[]) => Promise<void> | void;
+}
+export interface AgentOptions {
+    maxSteps?: number;
+    learnedActionsHint?: string;
+    customSystemPrompt?: string;
+    specFilePath?: string;
+    fnSource?: string;
+    fnResult?: {
+        error?: string;
+        success?: boolean;
+    };
+    hooks?: AgentHooks;
+    /** External abort signal (e.g. per-goal timeout). When aborted, internal abortController is also triggered. */
+    signal?: AbortSignal;
+}
+export declare class KevePageAgent {
+    readonly page: Page;
+    readonly maxSteps: number;
+    readonly llm: LLM;
+    events: AgentEvent[];
+    private abortController;
+    private systemPrompt;
+    /** Current execute options (set at start of execute(), accessible from hooks) */
+    options?: AgentOptions;
+    private hooks?;
+    constructor(page: Page, options?: {
+        maxSteps?: number;
+        customSystemPrompt?: string;
+        hooks?: AgentHooks;
+    });
+    /** Stop the current execution */
+    stop(): void;
+    /** Main Re-Act execute loop */
+    execute(step: string, expected: string, options?: AgentOptions): Promise<AgentResult>;
+    private pushObservation;
+    private assembleUserPrompt;
+    private buildMacroTool;
+    /** Save screenshot buffer to test artifacts (reuses already-captured buffer) */
+    private saveScreenshotBuffer;
+    /**
+     * Visual element location: uses LLM multimodal to identify element bbox in screenshot.
+     * Returns normalized bbox (0-1000 scale) for coordinate-based clicking.
+     */
+    visualLocateElement(screenshotBase64: string, description: string): Promise<{
+        found: boolean;
+        bbox?: number[];
+        analysis?: string;
+    }>;
+    /** Build final result */
+    private buildResult;
+}
+/**
+ * @deprecated Use `new KevePageAgent(page).execute(step, expected, options)` directly.
+ * Drop-in replacement for the old reactLoop function.
+ * Creates a KevePageAgent, runs it, and maps the result.
+ */
+export declare function reactLoop(page: Page, step: string, expected: string, options?: {
+    maxSteps?: number;
+    learnedActionsHint?: string;
+    specFilePath?: string;
+    fnSource?: string;
+    fnResult?: {
+        error?: string;
+        success?: boolean;
+    };
+    signal?: AbortSignal;
+}): Promise<{
+    actions: any[];
+    expectedMet: boolean;
+    conclusion?: 'pass' | 'fail' | 'blocked';
+    finalSnapshot: string;
+    agentScreenshots?: string[];
+}>;