Files
skillkit/packages/core/src/executor/engine.ts
T
Rohit Ghumare d3ffb79512 feat: add session memory system for cross-agent learning (#3)
* feat: add session memory system for cross-agent learning

Implements a lightweight, local-first memory system that works across
all 17 AI coding agents. Key features:

- YAML-based storage (no databases or external services)
- Three memory layers: Session, Project, and Global
- AI-powered compression of observations into learnings
- Cross-agent memory injection with relevance matching
- Progressive disclosure for token efficiency

Core modules:
- ObservationStore: Capture raw session observations
- LearningStore: Persist compressed learnings
- MemoryCompressor: AI/rule-based compression engine
- MemoryInjector: Context-aware memory retrieval
- MemoryObserver: Automatic observation capture

CLI commands (skillkit memory):
- status, search, list, show, compress, export
- import, clear, add, rate, config

TUI integration:
- New Memory screen with tabs (Learnings/Observations/Search)
- useMemory hook for state management
- Updated navigation and keybindings

Code quality improvements:
- Replaced nested ternaries with explicit functions
- Added named constants for magic numbers
- Simplified navigation with lookup map

* feat: add marketplace, testing, CI/CD, workflows, and fix dry-run bug

New Features:
- Skill Marketplace: Aggregates skills from GitHub repos with caching
- Skill Testing Framework: 18+ assertion types for skill validation
- CI/CD Integration: Templates for GitHub Actions, GitLab CI, CircleCI
- Workflow Orchestration: Wave-based parallel skill execution
- Session Management: Pause/resume support with state persistence
- Agent Execution: CLI spawning for claude/codex/gemini/opencode/goose

New CLI Commands:
- skillkit marketplace - Browse and install from marketplace
- skillkit test - Run skill tests with assertions
- skillkit run - Execute skills with orchestration
- skillkit status - Show session state
- skillkit pause/resume - Session management
- skillkit workflow - Workflow management

New TUI Screens:
- Marketplace browser with search
- History viewer with session details
- Workflow management screen

Bug Fix:
- Fixed dry-run mode in memory compress command (Devin review)
  The --dry-run flag now properly prevents storing learnings

* fix: add missing yaml dependency to @skillkit/cli

* chore: update pnpm-lock.yaml

* fix: address 7 bugs identified by Devin code review

- Fix MemoryIndexStore ignoring isGlobal flag (memory-index.ts)
- Fix ESM runtime crash using require('yaml') in test runner (runner.ts)
- Fix ESM runtime crash using require('node:fs') in MarketplaceAggregator (aggregator.ts)
- Fix ESM runtime crash using require('node:fs') in SessionManager (manager.ts)
- Fix memory rate command parsing rating from --content instead of positional arg (memory.ts)
- Fix SkillExecutionEngine emitting failed status for paused executions (engine.ts)
- Fix run command misclassifying directories as skill markdown files (run.ts)

* fix: address CodeRabbit/Devin review issues (batch 2)

- Fix resume skipping checkpoint handling in engine.ts
- Add paused status guard before completeExecution call
- Fix NaN% progress when totalSteps=0 in Execute.tsx
- Fix effectiveness ?? instead of || to preserve 0% values in compressor.ts
- Clear cache on source change in aggregator.ts addSource/removeSource

* fix: address critical and major CodeRabbit/Devin issues (batch 3)

Security fixes:
- Remove shell: true from spawn to prevent shell injection (agents.ts)
- Add safe regex test with ReDoS protection (engine.ts)
- Add security warning for verification commands (engine.ts)

Bug fixes:
- Fix global memory index path to use ~/.skillkit/ (compressor.ts, memory-index.ts)
- Add task_complete events and verification to resumeExecution (engine.ts)
- Handle absolute URLs in skill entries (aggregator.ts)
- Implement actual port availability check (runner.ts)
- Remove invalid JUnit report format (templates.ts)
- Add crash guard to workflow list command (workflow/list.ts)

* fix: address remaining CodeRabbit/Devin issues (batch 4)

- ReDoS protection: Add pattern validator to reject dangerous regex patterns
  (nested quantifiers, overlapping alternations, excessive quantifiers)
- Add missing 'cancelled' status message in execution engine
- Make completedAt/durationMs optional in TaskExecutionResult
- Fix tag filter to skip untagged tests when tags are specified
- Improve error-solution matching: require keyword similarity + solution indicator
- Validate --limit and sanitize --tags in memory/marketplace CLI commands
- Guard against missing arrays when importing YAML learnings
- Escape YAML frontmatter values to prevent invalid output
- Preserve original learning source when merging learnings
- Fix keyword double-counting in memory index search
- Normalize keywords by stripping punctuation for better matching
2026-01-23 18:12:15 +00:00

612 lines
18 KiB
TypeScript

/**
* Skill Execution Engine
*
* Executes skills with task-based orchestration, verification, and state management.
*/
import { execSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import type {
ExecutableSkill,
ExecutableTask,
ExecutionOptions,
TaskExecutionResult,
SkillExecutionResult,
CheckpointHandler,
CheckpointResponse,
ExecutionTaskStatus,
} from './types.js';
import { SessionManager } from '../session/manager.js';
import type { SessionTask } from '../session/types.js';
/**
* Progress event for execution
*/
export interface ExecutionProgressEvent {
type: 'task_start' | 'task_complete' | 'checkpoint' | 'verification' | 'complete';
taskId?: string;
taskName?: string;
taskIndex?: number;
totalTasks?: number;
status?: ExecutionTaskStatus | 'paused' | 'cancelled';
message?: string;
error?: string;
}
/**
* Progress callback type
*/
export type ExecutionProgressCallback = (event: ExecutionProgressEvent) => void;
/**
* Skill Execution Engine
*/
export class SkillExecutionEngine {
private projectPath: string;
private sessionManager: SessionManager;
private checkpointHandler?: CheckpointHandler;
private onProgress?: ExecutionProgressCallback;
constructor(
projectPath: string,
options?: {
checkpointHandler?: CheckpointHandler;
onProgress?: ExecutionProgressCallback;
}
) {
this.projectPath = projectPath;
this.sessionManager = new SessionManager(projectPath);
this.checkpointHandler = options?.checkpointHandler;
this.onProgress = options?.onProgress;
}
/**
* Execute a skill
*/
async execute(
skill: ExecutableSkill,
options: ExecutionOptions = {}
): Promise<SkillExecutionResult> {
const startTime = new Date();
const tasks = skill.tasks || [];
// Handle dry run
if (options.dryRun) {
return this.createDryRunResult(skill);
}
// Check if there's an existing paused execution for this skill
const existingState = this.sessionManager.get();
if (existingState?.currentExecution?.skillName === skill.name) {
if (existingState.currentExecution.status === 'paused') {
// Resume from paused state
return this.resumeExecution(skill, options);
}
}
// Start new execution
const sessionTasks: Omit<SessionTask, 'status'>[] = tasks.map((task, index) => ({
id: task.id || `task-${index}`,
name: task.name,
type: task.type === 'auto' ? 'auto' : task.type,
}));
this.sessionManager.startExecution(skill.name, skill.source, sessionTasks);
const taskResults: TaskExecutionResult[] = [];
let overallStatus: 'completed' | 'failed' | 'cancelled' | 'paused' = 'completed';
let overallError: string | undefined;
// Execute tasks
for (let i = 0; i < tasks.length; i++) {
const task = tasks[i];
this.onProgress?.({
type: 'task_start',
taskId: task.id,
taskName: task.name,
taskIndex: i,
totalTasks: tasks.length,
});
// Handle checkpoints
if (task.type !== 'auto') {
const checkpointResult = await this.handleCheckpoint(task, {
skillName: skill.name,
taskIndex: i,
totalTasks: tasks.length,
});
if (!checkpointResult.continue) {
overallStatus = 'paused';
this.sessionManager.pause();
break;
}
// For decision checkpoints, record the decision
if (task.type === 'checkpoint:decision' && checkpointResult.selectedOption) {
this.sessionManager.recordDecision(
`${skill.name}:${task.id}`,
checkpointResult.selectedOption,
skill.name
);
}
}
// Execute the task
const taskResult = await this.executeTask(task, skill, options);
taskResults.push(taskResult);
this.sessionManager.updateTask(task.id || `task-${i}`, {
status: taskResult.status === 'completed' ? 'completed' : 'failed',
output: taskResult.output,
error: taskResult.error,
filesModified: taskResult.filesModified,
commitSha: taskResult.commitSha,
});
this.onProgress?.({
type: 'task_complete',
taskId: task.id,
taskName: task.name,
taskIndex: i,
totalTasks: tasks.length,
status: taskResult.status,
error: taskResult.error,
});
// Handle task failure
if (taskResult.status === 'failed') {
if (!options.continueOnError) {
overallStatus = 'failed';
overallError = taskResult.error;
break;
}
}
// Run verification if enabled
if (options.verify && task.verify) {
const verificationPassed = await this.runVerification(task, taskResult);
if (!verificationPassed && !options.continueOnError) {
overallStatus = 'failed';
overallError = 'Verification failed';
break;
}
}
}
const endTime = new Date();
// Complete the execution
if (overallStatus !== 'paused') {
this.sessionManager.completeExecution(overallStatus, overallError);
}
const result: SkillExecutionResult = {
skillName: skill.name,
skillSource: skill.source,
status: overallStatus,
startedAt: startTime.toISOString(),
completedAt: endTime.toISOString(),
durationMs: endTime.getTime() - startTime.getTime(),
tasks: taskResults,
filesModified: Array.from(new Set(taskResults.flatMap((t) => t.filesModified || []))),
commits: taskResults.map((t) => t.commitSha).filter((sha): sha is string => !!sha),
error: overallError,
};
const statusMessages: Record<'completed' | 'failed' | 'cancelled' | 'paused', string> = {
completed: 'Skill execution completed',
paused: 'Skill execution paused',
failed: overallError || 'Skill execution failed',
cancelled: 'Skill execution cancelled',
};
this.onProgress?.({
type: 'complete',
status: overallStatus,
message: statusMessages[overallStatus],
});
return result;
}
/**
* Resume a paused execution
*/
private async resumeExecution(
skill: ExecutableSkill,
options: ExecutionOptions
): Promise<SkillExecutionResult> {
const state = this.sessionManager.get();
if (!state?.currentExecution) {
throw new Error('No execution to resume');
}
this.sessionManager.resume();
const execution = state.currentExecution;
const tasks = skill.tasks || [];
const taskResults: TaskExecutionResult[] = [];
let overallStatus: 'completed' | 'failed' | 'cancelled' | 'paused' = 'completed';
let overallError: string | undefined;
// Find where to resume from
const startIndex = execution.currentStep;
for (let i = startIndex; i < tasks.length; i++) {
const task = tasks[i];
this.onProgress?.({
type: 'task_start',
taskId: task.id,
taskName: task.name,
taskIndex: i,
totalTasks: tasks.length,
});
// Handle checkpoints (same as in execute)
if (task.type !== 'auto') {
const checkpointResult = await this.handleCheckpoint(task, {
skillName: skill.name,
taskIndex: i,
totalTasks: tasks.length,
});
if (!checkpointResult.continue) {
overallStatus = 'paused';
this.sessionManager.pause();
break;
}
// For decision checkpoints, record the decision
if (task.type === 'checkpoint:decision' && checkpointResult.selectedOption) {
this.sessionManager.recordDecision(
`${skill.name}:${task.id}`,
checkpointResult.selectedOption,
skill.name
);
}
}
const taskResult = await this.executeTask(task, skill, options);
taskResults.push(taskResult);
this.sessionManager.updateTask(task.id || `task-${i}`, {
status: taskResult.status === 'completed' ? 'completed' : 'failed',
output: taskResult.output,
error: taskResult.error,
filesModified: taskResult.filesModified,
commitSha: taskResult.commitSha,
});
// Emit task_complete progress event (matching execute behavior)
this.onProgress?.({
type: 'task_complete',
taskId: task.id,
taskName: task.name,
taskIndex: i,
totalTasks: tasks.length,
status: taskResult.status,
error: taskResult.error,
});
// Handle task failure
if (taskResult.status === 'failed') {
if (!options.continueOnError) {
overallStatus = 'failed';
overallError = taskResult.error;
break;
}
}
// Run verification if enabled (matching execute behavior)
if (options.verify && task.verify) {
const verificationPassed = await this.runVerification(task, taskResult);
if (!verificationPassed && !options.continueOnError) {
overallStatus = 'failed';
overallError = 'Verification failed';
break;
}
}
}
// Only complete execution if not paused
if (overallStatus !== 'paused') {
this.sessionManager.completeExecution(overallStatus, overallError);
}
return {
skillName: skill.name,
skillSource: skill.source,
status: overallStatus,
startedAt: execution.startedAt,
completedAt: new Date().toISOString(),
durationMs: Date.now() - new Date(execution.startedAt).getTime(),
tasks: taskResults,
filesModified: Array.from(new Set(taskResults.flatMap((t) => t.filesModified || []))),
commits: taskResults.map((t) => t.commitSha).filter((sha): sha is string => !!sha),
error: overallError,
};
}
/**
* Execute a single task
*/
private async executeTask(
task: ExecutableTask,
_skill: ExecutableSkill,
_options: ExecutionOptions
): Promise<TaskExecutionResult> {
const startTime = new Date();
const taskId = task.id || randomUUID();
try {
// For now, we simulate task execution
// In a real implementation, this would integrate with the AI agent
// to execute the task action based on the skill content
// Simulate some work
await new Promise((resolve) => setTimeout(resolve, 100));
const endTime = new Date();
return {
taskId,
taskName: task.name,
status: 'completed',
startedAt: startTime.toISOString(),
completedAt: endTime.toISOString(),
durationMs: endTime.getTime() - startTime.getTime(),
output: `Task "${task.name}" completed successfully`,
filesModified: task.files,
};
} catch (error) {
const endTime = new Date();
return {
taskId,
taskName: task.name,
status: 'failed',
startedAt: startTime.toISOString(),
completedAt: endTime.toISOString(),
durationMs: endTime.getTime() - startTime.getTime(),
error: error instanceof Error ? error.message : String(error),
};
}
}
/**
* Handle a checkpoint
*/
private async handleCheckpoint(
task: ExecutableTask,
context: { skillName: string; taskIndex: number; totalTasks: number }
): Promise<CheckpointResponse> {
this.onProgress?.({
type: 'checkpoint',
taskId: task.id,
taskName: task.name,
taskIndex: context.taskIndex,
totalTasks: context.totalTasks,
message: `Checkpoint: ${task.type}`,
});
if (this.checkpointHandler) {
return this.checkpointHandler(task, context);
}
// Default: auto-continue for non-decision checkpoints
if (task.type === 'checkpoint:decision') {
// Use first option if no handler
return {
continue: true,
selectedOption: task.options?.[0],
};
}
return { continue: true };
}
/**
* Check if a regex pattern is potentially dangerous (ReDoS-vulnerable)
* Rejects patterns with nested quantifiers and other known problematic constructs
*/
private isUnsafeRegexPattern(pattern: string): boolean {
// Detect nested quantifiers like (a+)+, (a*)+, (a+)*, (a*)*
// These are the primary cause of catastrophic backtracking
const nestedQuantifierPattern = /\([^)]*[+*][^)]*\)[+*?]/;
if (nestedQuantifierPattern.test(pattern)) {
return true;
}
// Detect overlapping alternations with quantifiers like (a|a)+
const overlappingAlternation = /\([^|)]*\|[^|)]*\)[+*]/;
if (overlappingAlternation.test(pattern)) {
return true;
}
// Detect excessive quantifiers (more than 3 quantifiers in a row-ish)
const quantifierCount = (pattern.match(/[+*?]|\{\d+/g) || []).length;
if (quantifierCount > 10) {
return true;
}
// Detect very long character classes which can be slow
const longCharClass = /\[[^\]]{50,}\]/;
if (longCharClass.test(pattern)) {
return true;
}
return false;
}
/**
* Safely test a regex pattern with ReDoS prevention
*
* This method validates patterns before execution to prevent catastrophic backtracking.
* Note: This cannot guarantee protection against all ReDoS patterns, but catches common ones.
*/
private safeRegexTest(pattern: string, input: string, _timeoutMs = 1000): boolean {
// Strict length limits to prevent excessive processing
if (pattern.length > 200 || input.length > 50000) {
console.warn(`Regex test skipped: pattern or input too long`);
return false;
}
// Reject patterns known to cause ReDoS
if (this.isUnsafeRegexPattern(pattern)) {
console.warn(`Regex pattern rejected as potentially unsafe: ${pattern.slice(0, 50)}...`);
return false;
}
try {
const regex = new RegExp(pattern);
return regex.test(input);
} catch {
// Invalid regex pattern
return false;
}
}
/**
* Run verification for a task
*
* SECURITY NOTE: Verification commands are executed from skill configuration.
* Only run skills from trusted sources. Commands run with the same privileges
* as the skillkit process.
*/
private async runVerification(
task: ExecutableTask,
result: TaskExecutionResult
): Promise<boolean> {
if (!task.verify) {
return true;
}
const verificationResults = {
automated: [] as { rule: string; passed: boolean; output?: string }[],
human: [] as { description: string; passed: boolean }[],
};
// Run automated verification
if (task.verify.automated) {
for (const rule of task.verify.automated) {
if (rule.command) {
try {
// SECURITY: Commands are from skill config - only run trusted skills
const output = execSync(rule.command, {
cwd: this.projectPath,
encoding: 'utf-8',
timeout: 30000,
});
let passed = true;
if (rule.expect) {
if (rule.expect === 'success') {
passed = true;
} else if (rule.expect.startsWith('contains:')) {
const expected = rule.expect.slice(9);
passed = output.includes(expected);
} else if (rule.expect.startsWith('matches:')) {
const pattern = rule.expect.slice(8);
// Use safe regex test to prevent ReDoS
passed = this.safeRegexTest(pattern, output);
}
}
verificationResults.automated.push({
rule: rule.command,
passed,
output,
});
this.onProgress?.({
type: 'verification',
taskId: task.id,
taskName: task.name,
message: `Verification ${passed ? 'passed' : 'failed'}: ${rule.command}`,
});
if (!passed) {
return false;
}
} catch (error) {
verificationResults.automated.push({
rule: rule.command,
passed: false,
output: error instanceof Error ? error.message : String(error),
});
return false;
}
}
}
}
// Human verification would be handled by checkpoint handler
result.verificationResults = verificationResults;
return true;
}
/**
* Create a dry run result
*/
private createDryRunResult(skill: ExecutableSkill): SkillExecutionResult {
const tasks = skill.tasks || [];
return {
skillName: skill.name,
skillSource: skill.source,
status: 'completed',
startedAt: new Date().toISOString(),
completedAt: new Date().toISOString(),
durationMs: 0,
tasks: tasks.map((task) => ({
taskId: task.id || randomUUID(),
taskName: task.name,
status: 'skipped' as ExecutionTaskStatus,
startedAt: new Date().toISOString(),
completedAt: new Date().toISOString(),
durationMs: 0,
output: '[Dry run - not executed]',
})),
filesModified: [],
commits: [],
};
}
/**
* Pause current execution
*/
pause(): boolean {
return this.sessionManager.pause();
}
/**
* Check if execution is paused
*/
isPaused(): boolean {
return this.sessionManager.isPaused();
}
/**
* Get session manager
*/
getSessionManager(): SessionManager {
return this.sessionManager;
}
}
/**
* Create a new skill execution engine
*/
export function createExecutionEngine(
projectPath: string,
options?: {
checkpointHandler?: CheckpointHandler;
onProgress?: ExecutionProgressCallback;
}
): SkillExecutionEngine {
return new SkillExecutionEngine(projectPath, options);
}