@compilr-dev/agents 0.0.1

package/dist/skills/index.js

@@ -0,0 +1,282 @@
+/**
+ * Skills System - Prompt expansions for specialized agent behavior
+ *
+ * Skills are reusable prompt templates that can be invoked to provide
+ * specialized capabilities to agents. They allow you to define
+ * domain-specific instructions that can be dynamically added to conversations.
+ */
+/**
+ * Skill Registry - Manages skill registration and invocation
+ */
+export class SkillRegistry {
+    skills = new Map();
+    /**
+     * Register a new skill
+     */
+    register(skill) {
+        if (!skill.name || skill.name.trim() === '') {
+            throw new Error('Skill name is required');
+        }
+        if (!skill.prompt || skill.prompt.trim() === '') {
+            throw new Error('Skill prompt is required');
+        }
+        this.skills.set(skill.name, {
+            ...skill,
+            enabled: skill.enabled ?? true,
+        });
+    }
+    /**
+     * Register multiple skills at once
+     */
+    registerAll(skills) {
+        for (const skill of skills) {
+            this.register(skill);
+        }
+    }
+    /**
+     * Get a skill by name
+     */
+    get(name) {
+        return this.skills.get(name);
+    }
+    /**
+     * Check if a skill exists
+     */
+    has(name) {
+        return this.skills.has(name);
+    }
+    /**
+     * Get all registered skills
+     */
+    getAll() {
+        return Array.from(this.skills.values());
+    }
+    /**
+     * Get all enabled skills
+     */
+    getEnabled() {
+        return this.getAll().filter((s) => s.enabled !== false);
+    }
+    /**
+     * Get skills by tag
+     */
+    getByTag(tag) {
+        return this.getAll().filter((s) => s.tags?.includes(tag));
+    }
+    /**
+     * Get skill names
+     */
+    getNames() {
+        return Array.from(this.skills.keys());
+    }
+    /**
+     * Remove a skill
+     */
+    remove(name) {
+        return this.skills.delete(name);
+    }
+    /**
+     * Clear all skills
+     */
+    clear() {
+        this.skills.clear();
+    }
+    /**
+     * Enable a skill
+     */
+    enable(name) {
+        const skill = this.skills.get(name);
+        if (!skill)
+            return false;
+        skill.enabled = true;
+        return true;
+    }
+    /**
+     * Disable a skill
+     */
+    disable(name) {
+        const skill = this.skills.get(name);
+        if (!skill)
+            return false;
+        skill.enabled = false;
+        return true;
+    }
+    /**
+     * Invoke a skill by name
+     */
+    invoke(name, options) {
+        const skill = this.skills.get(name);
+        if (!skill) {
+            return {
+                skill: { name, description: '', prompt: '' },
+                prompt: '',
+                success: false,
+                error: `Skill not found: ${name}`,
+            };
+        }
+        if (skill.enabled === false) {
+            return {
+                skill,
+                prompt: '',
+                success: false,
+                error: `Skill is disabled: ${name}`,
+            };
+        }
+        let prompt = skill.prompt;
+        // Interpolate variables
+        if (options?.variables) {
+            for (const [key, value] of Object.entries(options.variables)) {
+                prompt = prompt.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value);
+            }
+        }
+        // Add context if provided
+        if (options?.context) {
+            prompt = `${options.context}\n\n${prompt}`;
+        }
+        return {
+            skill,
+            prompt,
+            success: true,
+        };
+    }
+    /**
+     * Get skill count
+     */
+    get size() {
+        return this.skills.size;
+    }
+}
+/**
+ * Helper function to define a skill
+ */
+export function defineSkill(options) {
+    return {
+        name: options.name,
+        description: options.description,
+        prompt: options.prompt,
+        tags: options.tags,
+        version: options.version,
+        enabled: options.enabled ?? true,
+    };
+}
+/**
+ * Create a new skill registry
+ */
+export function createSkillRegistry() {
+    return new SkillRegistry();
+}
+/**
+ * Built-in skills that are commonly useful
+ */
+export const builtinSkills = [
+    defineSkill({
+        name: 'code-review',
+        description: 'Perform a thorough code review',
+        prompt: `You are now in code review mode. When reviewing code:
+
+1. **Security**: Check for vulnerabilities (injection, XSS, auth issues)
+2. **Performance**: Identify bottlenecks and optimization opportunities
+3. **Maintainability**: Evaluate code clarity, naming, and structure
+4. **Best Practices**: Check for anti-patterns and code smells
+5. **Testing**: Assess test coverage and edge cases
+
+Provide specific, actionable feedback with line references.
+Format: List issues by severity (Critical, High, Medium, Low).`,
+        tags: ['development', 'review'],
+    }),
+    defineSkill({
+        name: 'debug',
+        description: 'Systematic debugging approach',
+        prompt: `You are now in debugging mode. Follow this systematic approach:
+
+1. **Reproduce**: Ensure the issue can be consistently reproduced
+2. **Isolate**: Narrow down the scope to specific components
+3. **Analyze**: Examine logs, stack traces, and state
+4. **Hypothesize**: Form theories about root cause
+5. **Test**: Verify hypotheses with targeted tests
+6. **Fix**: Implement and validate the fix
+7. **Document**: Note the issue and solution for future reference
+
+Be methodical and avoid jumping to conclusions.`,
+        tags: ['development', 'troubleshooting'],
+    }),
+    defineSkill({
+        name: 'explain',
+        description: 'Explain code or concepts clearly',
+        prompt: `You are now in explanation mode. When explaining:
+
+1. Start with a high-level overview
+2. Break down complex concepts into smaller parts
+3. Use analogies and examples where helpful
+4. Highlight key points and takeaways
+5. Provide context for why things work the way they do
+6. Tailor complexity to the audience level
+
+Be clear, concise, and avoid unnecessary jargon.`,
+        tags: ['education', 'documentation'],
+    }),
+    defineSkill({
+        name: 'refactor',
+        description: 'Guide code refactoring',
+        prompt: `You are now in refactoring mode. When refactoring:
+
+1. **Understand**: Fully understand existing behavior before changing
+2. **Test First**: Ensure tests exist to catch regressions
+3. **Small Steps**: Make incremental, reversible changes
+4. **Single Purpose**: Each refactor should have one clear goal
+5. **Preserve Behavior**: No functional changes during refactoring
+6. **Clean Up**: Remove dead code, simplify complexity
+
+Follow established patterns and maintain consistency with the codebase.`,
+        tags: ['development', 'improvement'],
+    }),
+    defineSkill({
+        name: 'planning',
+        description: 'Help plan and structure work',
+        prompt: `You are now in planning mode. When planning:
+
+1. **Clarify Goals**: Understand the desired outcome
+2. **Break Down**: Divide into manageable tasks
+3. **Dependencies**: Identify task dependencies and order
+4. **Risks**: Anticipate potential blockers
+5. **Milestones**: Define checkpoints to measure progress
+6. **Resources**: Identify what's needed
+
+Provide actionable plans with clear next steps.`,
+        tags: ['project-management', 'organization'],
+    }),
+    defineSkill({
+        name: 'security-review',
+        description: 'Focus on security aspects',
+        prompt: `You are now in security review mode. Focus on:
+
+1. **Authentication**: Verify proper auth mechanisms
+2. **Authorization**: Check access control at every level
+3. **Input Validation**: Look for injection vulnerabilities
+4. **Data Protection**: Ensure sensitive data is protected
+5. **Dependencies**: Check for known vulnerabilities
+6. **Configuration**: Review security settings
+7. **Logging**: Verify security events are logged
+
+Apply OWASP guidelines and security best practices.`,
+        tags: ['security', 'review'],
+    }),
+];
+/**
+ * Default skill registry with built-in skills
+ */
+const defaultRegistry = new SkillRegistry();
+defaultRegistry.registerAll(builtinSkills);
+/**
+ * Get the default skill registry
+ */
+export function getDefaultSkillRegistry() {
+    return defaultRegistry;
+}
+/**
+ * Reset the default registry to built-in skills only
+ */
+export function resetDefaultSkillRegistry() {
+    defaultRegistry.clear();
+    defaultRegistry.registerAll(builtinSkills);
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Agent State Utilities
+ *
+ * Helper functions for serializing and restoring agent state.
+ */
+import type { Message } from '../providers/types.js';
+import type { TodoItem } from '../tools/builtin/todo.js';
+import type { AgentState } from './types.js';
+/**
+ * Generate a new session ID
+ */
+export declare function generateSessionId(): string;
+/**
+ * Create an empty agent state
+ */
+export declare function createEmptyState(sessionId: string, systemPrompt: string): AgentState;
+/**
+ * Create agent state from current agent state
+ */
+export declare function createAgentState(options: {
+    sessionId: string;
+    systemPrompt: string;
+    model?: string;
+    messages: Message[];
+    todos: TodoItem[];
+    currentIteration: number;
+    totalTokensUsed: number;
+    createdAt?: string;
+}): AgentState;
+/**
+ * Serialize todos (convert Date to ISO string)
+ */
+export declare function serializeTodos(todos: TodoItem[]): TodoItem[];
+/**
+ * Deserialize todos (convert ISO string back to Date)
+ */
+export declare function deserializeTodos(todos: TodoItem[]): TodoItem[];
+/**
+ * Update state's updatedAt timestamp
+ */
+export declare function touchState(state: AgentState): AgentState;

package/dist/state/agent-state.js

@@ -0,0 +1,88 @@
+/**
+ * Agent State Utilities
+ *
+ * Helper functions for serializing and restoring agent state.
+ */
+import { CURRENT_STATE_VERSION } from './types.js';
+import { generateId } from '../utils/index.js';
+/**
+ * Generate a new session ID
+ */
+export function generateSessionId() {
+    return `session_${generateId()}`;
+}
+/**
+ * Create an empty agent state
+ */
+export function createEmptyState(sessionId, systemPrompt) {
+    const now = new Date().toISOString();
+    return {
+        sessionId,
+        messages: [],
+        systemPrompt,
+        todos: [],
+        currentIteration: 0,
+        totalTokensUsed: 0,
+        createdAt: now,
+        updatedAt: now,
+        version: CURRENT_STATE_VERSION,
+    };
+}
+/**
+ * Create agent state from current agent state
+ */
+export function createAgentState(options) {
+    const now = new Date().toISOString();
+    return {
+        sessionId: options.sessionId,
+        messages: options.messages,
+        systemPrompt: options.systemPrompt,
+        model: options.model,
+        todos: serializeTodos(options.todos),
+        currentIteration: options.currentIteration,
+        totalTokensUsed: options.totalTokensUsed,
+        createdAt: options.createdAt || now,
+        updatedAt: now,
+        version: CURRENT_STATE_VERSION,
+    };
+}
+/**
+ * Serialize todos (convert Date to ISO string)
+ */
+export function serializeTodos(todos) {
+    return todos.map((todo) => ({
+        ...todo,
+        // Convert Date objects to ISO strings for JSON serialization
+        createdAt: todo.createdAt instanceof Date
+            ? todo.createdAt
+            : new Date(todo.createdAt),
+        updatedAt: todo.updatedAt instanceof Date
+            ? todo.updatedAt
+            : new Date(todo.updatedAt),
+    }));
+}
+/**
+ * Deserialize todos (convert ISO string back to Date)
+ */
+export function deserializeTodos(todos) {
+    return todos.map((todo) => {
+        const createdAt = new Date(todo.createdAt);
+        // updatedAt might be undefined in stored state
+        const rawUpdatedAt = todo.updatedAt;
+        const updatedAt = rawUpdatedAt ? new Date(rawUpdatedAt) : createdAt; // Default to createdAt if undefined
+        return {
+            ...todo,
+            createdAt,
+            updatedAt,
+        };
+    });
+}
+/**
+ * Update state's updatedAt timestamp
+ */
+export function touchState(state) {
+    return {
+        ...state,
+        updatedAt: new Date().toISOString(),
+    };
+}

package/dist/state/checkpointer.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Checkpointer Implementations
+ *
+ * Built-in checkpointers for state persistence.
+ */
+import type { AgentState, Checkpointer, SessionMetadata, SessionInfo, ListSessionsOptions, StateSerializer } from './types.js';
+/**
+ * In-memory checkpointer for development and testing.
+ * State is lost when the process exits.
+ */
+export declare class MemoryCheckpointer implements Checkpointer {
+    private readonly sessions;
+    /**
+     * Save state to memory
+     *
+     * Pre-validates state before saving to prevent corrupted checkpoints.
+     * This catches issues like invalid data types that would fail on reload.
+     */
+    save(sessionId: string, state: AgentState, metadataOverrides?: Partial<SessionMetadata>): Promise<void>;
+    /**
+     * Load state from memory
+     */
+    load(sessionId: string): Promise<AgentState | null>;
+    /**
+     * List all sessions
+     */
+    list(options?: ListSessionsOptions): Promise<SessionInfo[]>;
+    /**
+     * Delete a session
+     */
+    delete(sessionId: string): Promise<boolean>;
+    /**
+     * Check if session exists
+     */
+    exists(sessionId: string): Promise<boolean>;
+    /**
+     * Get session metadata
+     */
+    getMetadata(sessionId: string): Promise<SessionMetadata | null>;
+    /**
+     * Clear all sessions (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Get current session count
+     */
+    get size(): number;
+}
+/**
+ * Options for FileCheckpointer
+ */
+export interface FileCheckpointerOptions {
+    /**
+     * Custom serializer (defaults to JsonSerializer)
+     */
+    serializer?: StateSerializer;
+    /**
+     * File extension (defaults to '.json')
+     */
+    extension?: string;
+}
+/**
+ * File-based checkpointer for simple persistence.
+ * Stores each session as a separate JSON file.
+ */
+export declare class FileCheckpointer implements Checkpointer {
+    private readonly baseDir;
+    private readonly serializer;
+    private readonly extension;
+    constructor(baseDir: string, options?: FileCheckpointerOptions);
+    /**
+     * Get file path for a session
+     */
+    private getStatePath;
+    /**
+     * Get metadata file path for a session
+     */
+    private getMetadataPath;
+    /**
+     * Ensure base directory exists
+     */
+    private ensureDir;
+    /**
+     * Save state to file
+     *
+     * Pre-validates state before saving to prevent corrupted checkpoints.
+     * This catches issues like invalid data types that would fail on reload.
+     */
+    save(sessionId: string, state: AgentState, metadataOverrides?: Partial<SessionMetadata>): Promise<void>;
+    /**
+     * Load state from file
+     */
+    load(sessionId: string): Promise<AgentState | null>;
+    /**
+     * List all sessions
+     */
+    list(options?: ListSessionsOptions): Promise<SessionInfo[]>;
+    /**
+     * Delete a session
+     */
+    delete(sessionId: string): Promise<boolean>;
+    /**
+     * Check if session exists
+     */
+    exists(sessionId: string): Promise<boolean>;
+    /**
+     * Get session metadata
+     */
+    getMetadata(sessionId: string): Promise<SessionMetadata | null>;
+}