@webpresso/agent-kit 0.21.0

package/dist/esm/ai-tools/search-files.js

@@ -0,0 +1,166 @@
+import { getErrorMessage } from '#format/errors.js';
+import { isValidRelativePath } from './shared/validate-path.js';
+async function performSemanticSearch(pattern, maxResults, context) {
+    if (!context.ragRetriever) {
+        return {
+            success: false,
+            output: 'Semantic search unavailable: ragRetriever not configured',
+            error: 'ragRetriever missing in context',
+        };
+    }
+    try {
+        const results = await context.ragRetriever.retrieve(pattern, { topK: maxResults });
+        if (!results.chunks.length) {
+            return {
+                success: true,
+                output: `No semantic matches found for query: ${pattern}`,
+                data: { pattern, matches: [], count: 0, semantic: true },
+            };
+        }
+        const formatted = results.chunks
+            .map((r) => {
+            const meta = r.chunk.metadata;
+            const filepath = meta?.filepath ?? 'unknown';
+            const startLine = meta?.startLine;
+            const endLine = meta?.endLine;
+            const location = startLine && endLine ? `${filepath}:${startLine}-${endLine}` : filepath;
+            const snippet = (r.chunk.content || '').split('\n').slice(0, 6).join('\n');
+            return `${location}\n${snippet}\n(score: ${r.score.toFixed(2)})`;
+        })
+            .join('\n\n');
+        return {
+            success: true,
+            output: formatted,
+            data: {
+                pattern,
+                matches: results.chunks,
+                count: results.chunks.length,
+                semantic: true,
+            },
+        };
+    }
+    catch (error) {
+        const message = getErrorMessage(error);
+        return {
+            success: false,
+            output: `Semantic search failed: ${message}`,
+            error: message,
+        };
+    }
+}
+async function performRegexSearch(pattern, path, filePattern, caseSensitive, maxResults, context) {
+    if (!context.storage) {
+        return {
+            success: false,
+            output: 'Storage adapter not configured',
+            error: 'No storage adapter provided in context',
+        };
+    }
+    try {
+        const normalizedPath = path === '.' ? '' : path;
+        const matches = await context.storage.searchFiles(pattern, {
+            path: normalizedPath,
+            filePattern,
+            caseSensitive,
+            maxResults,
+        });
+        if (!matches.length) {
+            return {
+                success: true,
+                output: `No matches found for pattern: ${pattern}`,
+                data: { pattern, matches: [], count: 0 },
+            };
+        }
+        const formatted = matches
+            .map((m) => {
+            const highlighted = highlightMatch(m.content, m.matchStart, m.matchEnd);
+            return `${m.path}:${m.line}: ${highlighted}`;
+        })
+            .join('\n');
+        const truncated = matches.length >= maxResults ? `\n\n(Showing first ${maxResults} results)` : '';
+        return {
+            success: true,
+            output: formatted + truncated,
+            data: { pattern, matches, count: matches.length, truncated: matches.length >= maxResults },
+        };
+    }
+    catch (error) {
+        const message = getErrorMessage(error);
+        return {
+            success: false,
+            output: `Failed to search files: ${message}`,
+            error: message,
+        };
+    }
+}
+function highlightMatch(content, start, end) {
+    const before = content.slice(0, start);
+    const match = content.slice(start, end);
+    const after = content.slice(end);
+    return `${before}**${match}**${after}`;
+}
+export const searchFilesTool = {
+    name: 'search_files',
+    description: 'Search for a pattern in files. Returns matching lines with file paths and line numbers. Use this to find specific code, function definitions, or usages.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            pattern: {
+                type: 'string',
+                description: 'The search pattern (supports regex). Examples: "function handleSubmit", "import.*from", "TODO:"',
+            },
+            path: {
+                type: 'string',
+                description: 'The relative path to search in (e.g., "src" to search only in src/). Use "" or "." for entire project.',
+            },
+            filePattern: {
+                type: 'string',
+                description: 'Optional glob pattern to filter files to search (e.g., "*.ts", "*.tsx", "**/*.test.ts")',
+            },
+            semantic: {
+                type: 'boolean',
+                description: 'Use semantic search (RAG) instead of regex. Requires ragRetriever in context. Defaults to false.',
+            },
+            caseSensitive: {
+                type: 'boolean',
+                description: 'If true, search is case-sensitive. Defaults to false.',
+            },
+            maxResults: {
+                type: 'number',
+                description: 'Maximum number of results to return. Defaults to 50.',
+            },
+        },
+        required: ['pattern'],
+    },
+    execute(input, context) {
+        const pattern = input.pattern;
+        const path = input.path || '.';
+        const filePattern = input.filePattern;
+        const semantic = input.semantic ?? false;
+        const caseSensitive = input.caseSensitive ?? false;
+        const maxResults = input.maxResults ?? 50;
+        if (!isValidRelativePath(path)) {
+            return Promise.resolve({
+                success: false,
+                output: 'Invalid path: path traversal not allowed',
+                error: 'Path must be relative and cannot contain ".."',
+            });
+        }
+        if (semantic) {
+            return performSemanticSearch(pattern, maxResults, context);
+        }
+        try {
+            const regex = new RegExp(pattern, caseSensitive ? '' : 'i');
+            void regex;
+        }
+        catch {
+            return Promise.resolve({
+                success: false,
+                output: `Invalid regex pattern: ${pattern}`,
+                error: 'The search pattern is not a valid regular expression',
+            });
+        }
+        return performRegexSearch(pattern, path, filePattern, caseSensitive, maxResults, context);
+    },
+};
+//# sourceMappingURL=search-files.js.map

package/dist/esm/ai-tools/shared/validate-path.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Validates that a path is a safe relative path with no traversal or absolute references.
+ *
+ * Returns false if the path:
+ * - Contains `..` (directory traversal)
+ * - Starts with `/` (Unix absolute)
+ * - Starts with a drive letter like `C:\` (Windows absolute)
+ * - Starts with `\\` (Windows UNC)
+ */
+export declare function isValidRelativePath(path: string): boolean;
+//# sourceMappingURL=validate-path.d.ts.map

package/dist/esm/ai-tools/shared/validate-path.js

@@ -0,0 +1,25 @@
+/**
+ * Validates that a path is a safe relative path with no traversal or absolute references.
+ *
+ * Returns false if the path:
+ * - Contains `..` (directory traversal)
+ * - Starts with `/` (Unix absolute)
+ * - Starts with a drive letter like `C:\` (Windows absolute)
+ * - Starts with `\\` (Windows UNC)
+ */
+export function isValidRelativePath(path) {
+    if (path.includes('..')) {
+        return false;
+    }
+    if (path.startsWith('/')) {
+        return false;
+    }
+    if (/^[A-Za-z]:[\\/]/.test(path)) {
+        return false;
+    }
+    if (path.startsWith('\\\\')) {
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=validate-path.js.map

package/dist/esm/ai-tools/types.d.ts

@@ -0,0 +1,370 @@
+/** Metadata for a file or directory entry returned by list/stat operations. */
+export interface FileInfo {
+    path: string;
+    type: 'file' | 'directory';
+    size?: number;
+}
+/** A single search hit with position information within a file. */
+export interface SearchMatch {
+    path: string;
+    line: number;
+    content: string;
+    matchStart: number;
+    matchEnd: number;
+}
+/** Identifies who holds a lock on a file and when it was acquired. */
+export interface FileLock {
+    lockerId: string;
+    lockedAt: Date;
+}
+/** Describes the current lock state of a file. */
+export interface LockStatus {
+    locked: boolean;
+    lockerId?: string;
+    lockedAt?: Date;
+}
+/** Abstract storage interface for file operations used by AI tooling. */
+export interface StorageAdapter {
+    readFile(path: string, options?: {
+        startLine?: number;
+        endLine?: number;
+    }): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+    listFiles(path: string, options?: {
+        recursive?: boolean;
+        pattern?: string;
+    }): Promise<FileInfo[]>;
+    searchFiles(pattern: string, options?: {
+        path?: string;
+        filePattern?: string;
+        caseSensitive?: boolean;
+        maxResults?: number;
+    }): Promise<SearchMatch[]>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileInfo | null>;
+    lockFile(path: string, lockerId: string, options?: {
+        timeoutMs?: number;
+    }): Promise<boolean>;
+    unlockFile(path: string, lockerId: string): Promise<void>;
+    isLocked(path: string): Promise<LockStatus>;
+    unlockAll(lockerId: string): Promise<number>;
+}
+export type JSONSchema7TypeName = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
+export type JSONSchema7Type = string | number | boolean | JSONSchema7Object | JSONSchema7Array | null;
+export interface JSONSchema7Object {
+    [key: string]: JSONSchema7Type;
+}
+export interface JSONSchema7Array extends Array<JSONSchema7Type> {
+}
+export type JSONSchema7Definition = JSONSchema7 | boolean;
+export type JSONSchema7 = {
+    $schema?: string;
+    title?: string;
+    description?: string;
+    default?: unknown;
+    multipleOf?: number;
+    maximum?: number;
+    exclusiveMaximum?: number;
+    minimum?: number;
+    exclusiveMinimum?: number;
+    maxLength?: number;
+    minLength?: number;
+    pattern?: string;
+    additionalItems?: JSONSchema7Definition;
+    items?: JSONSchema7Definition | JSONSchema7Definition[];
+    maxItems?: number;
+    minItems?: number;
+    uniqueItems?: boolean;
+    contains?: JSONSchema7Definition;
+    maxProperties?: number;
+    minProperties?: number;
+    required?: string[];
+    additionalProperties?: JSONSchema7Definition;
+    definitions?: Record<string, JSONSchema7Definition>;
+    dependencies?: Record<string, JSONSchema7Definition | string[]>;
+    properties?: Record<string, JSONSchema7Definition>;
+    patternProperties?: Record<string, JSONSchema7Definition>;
+    type?: JSONSchema7TypeName | JSONSchema7TypeName[];
+    format?: string;
+    enum?: JSONSchema7Type[];
+    const?: JSONSchema7Type;
+    oneOf?: JSONSchema7Definition[];
+    anyOf?: JSONSchema7Definition[];
+    allOf?: JSONSchema7Definition[];
+    not?: JSONSchema7Definition;
+};
+export interface ChunkMetadata {
+    filepath: string;
+    startLine: number;
+    endLine: number;
+    language: string;
+    symbols: string[];
+    hasFunction: boolean;
+    hasClass: boolean;
+    indexedAt: number;
+    content?: string;
+}
+export interface CodeChunk {
+    id: string;
+    content: string;
+    metadata: ChunkMetadata;
+    embedding?: number[];
+}
+export interface RetrievalResult {
+    chunk: CodeChunk;
+    score: number;
+}
+export interface SearchOptions {
+    topK?: number;
+    minScore?: number;
+    pathFilters?: string[];
+    languageFilters?: string[];
+    symbolFilters?: string[];
+    functionsOnly?: boolean;
+    classesOnly?: boolean;
+}
+export interface RAGContext {
+    chunks: RetrievalResult[];
+    tokenCount: number;
+    formattedContext: string;
+}
+export interface RAGRetriever {
+    processVectorResults(results: Array<{
+        id: string;
+        score: number;
+        metadata?: Record<string, unknown>;
+    }>, minScore: number): RetrievalResult[];
+    retrieve(query: string, options?: SearchOptions): Promise<RAGContext>;
+    retrieveMultiple(queries: string[], options?: SearchOptions): Promise<RAGContext>;
+}
+export type FileOperation = 'create' | 'modify' | 'delete';
+export interface PendingChange {
+    id: string;
+    path: string;
+    originalContent: string | null;
+    newContent: string | null;
+    type: 'create' | 'modify' | 'delete';
+    status: 'pending' | 'accepted' | 'rejected';
+    createdAt: Date;
+    description?: string;
+}
+export type ChangeStatus = 'pending' | 'accepted' | 'rejected';
+export interface DiffLine {
+    type: 'context' | 'add' | 'remove';
+    content: string;
+    oldLineNumber?: number;
+    newLineNumber?: number;
+}
+export interface DiffHunk {
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+    lines: DiffLine[];
+}
+export interface UnifiedDiff {
+    path: string;
+    hunks: DiffHunk[];
+    additions: number;
+    deletions: number;
+}
+export interface PendingChangesManager {
+    addCreate(path: string, content: string, description?: string): PendingChange;
+    addModify(path: string, originalContent: string, newContent: string, description?: string): PendingChange;
+    addDelete(path: string, originalContent: string, description?: string): PendingChange;
+    getChanges(): PendingChange[];
+    getChangesByStatus(status: ChangeStatus): PendingChange[];
+    getChange(id: string): PendingChange | undefined;
+    getChangeByPath(path: string): PendingChange | undefined;
+    accept(id: string): boolean;
+    reject(id: string): boolean;
+    acceptAll(): number;
+    rejectAll(): number;
+    applyAccepted(storage: StorageAdapter): Promise<number>;
+    getDiff(id: string): UnifiedDiff | undefined;
+    getSummary(): {
+        total: number;
+        pending: number;
+        accepted: number;
+        rejected: number;
+        additions: number;
+        deletions: number;
+    };
+    clear(): void;
+    clearRejected(): number;
+}
+export interface FileChange {
+    id: string;
+    path: string;
+    before: string | null;
+    after: string | null;
+    operation: FileOperation;
+    timestamp: number;
+    toolCallId: string;
+}
+export interface RevertResult {
+    success: boolean;
+    path: string;
+    operation: FileOperation;
+    error?: string;
+}
+export interface ChangeTrackerDiff {
+    path: string;
+    changeId: string;
+    operation: FileOperation;
+    lines: Array<{
+        type: 'header' | 'context' | 'addition' | 'deletion';
+        content: string;
+        oldLineNumber?: number;
+        newLineNumber?: number;
+    }>;
+}
+export interface ChangeTracker {
+    getSessionId(): string;
+    recordChange(change: {
+        path: string;
+        before: string | null;
+        after: string | null;
+        operation: FileOperation;
+        toolCallId: string;
+    }): FileChange;
+    listChanges(): FileChange[];
+    getChangesForFile(path: string): FileChange[];
+    getChange(id: string): FileChange | undefined;
+    getDiff(changeId: string): ChangeTrackerDiff | null;
+    revert(changeId: string, storage: StorageAdapter): Promise<RevertResult>;
+    clear(): void;
+    size(): number;
+}
+export interface CommandRequest {
+    command: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    timeout?: number;
+    stream?: boolean;
+}
+export interface CommandOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    durationMs: number;
+}
+export type TerminalEvent = {
+    type: 'start';
+    executionId: string;
+    command: string;
+} | {
+    type: 'stdout';
+    executionId: string;
+    data: string;
+} | {
+    type: 'stderr';
+    executionId: string;
+    data: string;
+} | {
+    type: 'exit';
+    executionId: string;
+    exitCode: number;
+    durationMs: number;
+} | {
+    type: 'error';
+    executionId: string;
+    message: string;
+} | {
+    type: 'timeout';
+    executionId: string;
+};
+export interface CommandExecutor {
+    execute(request: CommandRequest): Promise<CommandOutput>;
+    executeStream(request: CommandRequest, onEvent: (event: TerminalEvent) => void): Promise<CommandOutput>;
+    kill(executionId: string): Promise<boolean>;
+    isRunning(executionId: string): Promise<boolean>;
+}
+export interface SessionSnapshot {
+    id: string;
+    timestamp: Date;
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    filesState: Map<string, string>;
+    description: string;
+}
+export interface SnapshotManager {
+    createSnapshot(toolName: string, toolInput: Record<string, unknown>): Promise<SessionSnapshot>;
+    restoreSnapshot(snapshotId: string): Promise<boolean>;
+    getSnapshots(): SessionSnapshot[];
+    getSnapshot(snapshotId: string): SessionSnapshot | undefined;
+    undo(): Promise<SessionSnapshot | undefined>;
+    clear(): void;
+}
+export interface GitAdapter {
+    getCurrentBranch(): Promise<string>;
+    getStatus(): Promise<Array<{
+        path: string;
+        status: string;
+    }>>;
+    getLog(depth?: number): Promise<Array<{
+        sha: string;
+        message: string;
+        author: {
+            name: string;
+            email: string;
+        };
+        timestamp: number;
+    }>>;
+    stageFile(filepath: string): Promise<void>;
+    unstageFile(filepath: string): Promise<void>;
+    commit(message: string, author: {
+        name: string;
+        email: string;
+    }): Promise<string>;
+    push(remote: string, options?: {
+        branch?: string;
+        force?: boolean;
+        token?: string;
+    }): Promise<void>;
+    pull(remote: string, options?: {
+        branch?: string;
+        token?: string;
+        author?: {
+            name: string;
+            email: string;
+        };
+    }): Promise<{
+        updated: boolean;
+        sha: string;
+    }>;
+    listBranches(): Promise<string[]>;
+    checkout(branch: string, options?: {
+        create?: boolean;
+    }): Promise<void>;
+    deleteBranch(branch: string): Promise<void>;
+}
+export interface ToolContext {
+    projectId: string;
+    orgId: string;
+    userId: string;
+    storage?: StorageAdapter;
+    ragRetriever?: RAGRetriever;
+    git?: GitAdapter;
+    executor?: CommandExecutor;
+    snapshotManager?: SnapshotManager;
+    pendingChanges?: PendingChangesManager;
+    changeTracker?: ChangeTracker;
+    lockerId?: string;
+    toolCallId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ToolResult {
+    success: boolean;
+    output: string;
+    data?: unknown;
+    error?: string;
+}
+export interface AgentTool {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema7;
+    execute: (input: Record<string, unknown>, context: ToolContext) => Promise<ToolResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/ai-tools/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/ai-tools/write-file.d.ts

@@ -0,0 +1,3 @@
+import type { AgentTool } from './types.js';
+export declare const writeFileTool: AgentTool;
+//# sourceMappingURL=write-file.d.ts.map