agentic-qe 3.8.13 → 3.9.0

package/dist/mcp/services/session-resume.js

@@ -0,0 +1,221 @@
+/**
+ * Agentic QE v3 - Session Resume Service
+ *
+ * IMP-04: Transcript-First Session Durability
+ * Reads an existing JSONL session file by sampling the head (first 4KB)
+ * and tail (last 64KB) to reconstruct metadata and recent entries
+ * without reading the entire file.
+ *
+ * @module mcp/services/session-resume
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+// ============================================================================
+// Constants
+// ============================================================================
+const HEAD_BYTES = 4 * 1024; // 4KB
+const TAIL_BYTES = 64 * 1024; // 64KB
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Resume a session from a JSONL file.
+ *
+ * Reads the first 4KB (head) to extract session start metadata and
+ * the last 64KB (tail) to get recent entries. Parses JSONL lines,
+ * reconstructs the parentUuid linked list, and returns metadata +
+ * recent entries + resume capability.
+ *
+ * Corrupt or incomplete lines are skipped gracefully.
+ */
+export function resumeSession(filePath) {
+    // If file doesn't exist, return non-resumable result
+    if (!fs.existsSync(filePath)) {
+        return {
+            metadata: {
+                sessionId: extractSessionId(filePath),
+                createdAt: 0,
+                lastActivityAt: 0,
+                entryCount: 0,
+                state: 'idle',
+            },
+            recentEntries: [],
+            lastState: 'idle',
+            canResume: false,
+        };
+    }
+    const stat = fs.statSync(filePath);
+    const fileSize = stat.size;
+    if (fileSize === 0) {
+        return {
+            metadata: {
+                sessionId: extractSessionId(filePath),
+                createdAt: 0,
+                lastActivityAt: 0,
+                entryCount: 0,
+                state: 'idle',
+            },
+            recentEntries: [],
+            lastState: 'idle',
+            canResume: false,
+        };
+    }
+    // Read head (first 4KB)
+    const headEntries = readHead(filePath, fileSize);
+    // Read tail (last 64KB)
+    const tailEntries = readTail(filePath, fileSize);
+    // Merge and deduplicate: use a Map keyed by uuid to ensure uniqueness
+    const entryMap = new Map();
+    for (const entry of headEntries) {
+        entryMap.set(entry.uuid, entry);
+    }
+    for (const entry of tailEntries) {
+        entryMap.set(entry.uuid, entry);
+    }
+    const allEntries = Array.from(entryMap.values());
+    allEntries.sort((a, b) => a.timestamp - b.timestamp);
+    // Reconstruct metadata from available entries
+    const firstEntry = headEntries[0] ?? allEntries[0];
+    const lastEntry = tailEntries[tailEntries.length - 1] ?? allEntries[allEntries.length - 1];
+    // For entry count: if file is small enough that head+tail overlap,
+    // allEntries.length is accurate. Otherwise, count total lines.
+    let entryCount;
+    if (fileSize <= HEAD_BYTES + TAIL_BYTES) {
+        entryCount = allEntries.length;
+    }
+    else {
+        entryCount = countLines(filePath);
+    }
+    const lastState = lastEntry?.state ?? 'idle';
+    const metadata = {
+        sessionId: extractSessionId(filePath),
+        createdAt: firstEntry?.timestamp ?? 0,
+        lastActivityAt: lastEntry?.timestamp ?? 0,
+        entryCount,
+        state: lastState,
+    };
+    return {
+        metadata,
+        recentEntries: tailEntries,
+        lastState,
+        canResume: allEntries.length > 0,
+    };
+}
+// ============================================================================
+// Private helpers
+// ============================================================================
+/**
+ * Extract session ID from file path (filename without extension).
+ */
+function extractSessionId(filePath) {
+    return path.basename(filePath, '.jsonl');
+}
+/**
+ * Read and parse the first HEAD_BYTES of the file.
+ */
+function readHead(filePath, fileSize) {
+    const bytesToRead = Math.min(HEAD_BYTES, fileSize);
+    const fd = fs.openSync(filePath, 'r');
+    try {
+        const buffer = Buffer.alloc(bytesToRead);
+        fs.readSync(fd, buffer, 0, bytesToRead, 0);
+        const text = buffer.toString('utf-8');
+        return parseJsonlLines(text, /* isHead */ true);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Read and parse the last TAIL_BYTES of the file.
+ */
+function readTail(filePath, fileSize) {
+    const bytesToRead = Math.min(TAIL_BYTES, fileSize);
+    const offset = Math.max(0, fileSize - bytesToRead);
+    const fd = fs.openSync(filePath, 'r');
+    try {
+        const buffer = Buffer.alloc(bytesToRead);
+        fs.readSync(fd, buffer, 0, bytesToRead, offset);
+        const text = buffer.toString('utf-8');
+        // When offset is 0, we read from the start of the file so
+        // the first line is complete -- don't skip it.
+        const isMidFileRead = offset > 0;
+        return parseJsonlLines(text, /* isHead */ false, isMidFileRead);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Parse JSONL text into SessionEntry[], skipping corrupt/incomplete lines.
+ * When reading from a mid-file offset (tail), the first partial line is skipped.
+ * When reading head, the last partial line is skipped if the chunk doesn't
+ * end with a newline.
+ *
+ * @param text - Raw text from the file chunk
+ * @param isHead - Whether this is a head read (skip trailing partial line)
+ * @param skipFirstLine - Whether to skip the first line (true for mid-file
+ *   tail reads where the first line is likely a partial). Defaults to !isHead.
+ */
+function parseJsonlLines(text, isHead, skipFirstLine) {
+    const lines = text.split('\n');
+    const entries = [];
+    // Default: skip first line for non-head reads (standard tail behavior)
+    const shouldSkipFirst = skipFirstLine ?? !isHead;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        // Skip first line of mid-file tail read (may be partial)
+        if (shouldSkipFirst && i === 0 && lines.length > 1)
+            continue;
+        // Skip last line of head read if it may be truncated
+        if (isHead && i === lines.length - 1 && lines.length > 1 && !text.endsWith('\n'))
+            continue;
+        try {
+            const entry = JSON.parse(line);
+            if (isValidEntry(entry)) {
+                entries.push(entry);
+            }
+        }
+        catch {
+            // Skip corrupt lines
+            continue;
+        }
+    }
+    return entries;
+}
+/**
+ * Minimal validation that a parsed object looks like a SessionEntry.
+ */
+function isValidEntry(obj) {
+    if (typeof obj !== 'object' || obj === null)
+        return false;
+    const entry = obj;
+    return (typeof entry.uuid === 'string' &&
+        typeof entry.timestamp === 'number' &&
+        typeof entry.type === 'string' &&
+        typeof entry.state === 'string');
+}
+/**
+ * Count total lines in a file (for large files where head+tail don't overlap).
+ * Only counts non-empty lines that parse as valid JSON.
+ */
+function countLines(filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    let count = 0;
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed) {
+            try {
+                JSON.parse(trimmed);
+                count++;
+            }
+            catch {
+                // Skip corrupt lines in count
+            }
+        }
+    }
+    return count;
+}
+//# sourceMappingURL=session-resume.js.map

package/dist/mcp/services/session-store.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Agentic QE v3 - Append-Only JSONL Session Store
+ *
+ * IMP-04: Transcript-First Session Durability
+ * Provides an append-only JSONL log of all tool calls, results, and state
+ * changes within a session. Supports write batching (100ms window) and
+ * lazy file creation (no file until first append).
+ *
+ * @module mcp/services/session-store
+ */
+export interface SessionEntry {
+    uuid: string;
+    parentUuid: string | null;
+    timestamp: number;
+    type: 'tool_call' | 'tool_result' | 'state_change' | 'error';
+    toolName?: string;
+    params?: Record<string, unknown>;
+    result?: unknown;
+    state: 'idle' | 'running' | 'requires_action';
+    tokenEstimate?: number;
+}
+export interface SessionMetadata {
+    sessionId: string;
+    createdAt: number;
+    lastActivityAt: number;
+    entryCount: number;
+    state: 'idle' | 'running' | 'requires_action';
+}
+export type SessionEntryInput = Omit<SessionEntry, 'uuid' | 'parentUuid'>;
+export declare class SessionStore {
+    private readonly sessionDir;
+    private sessionId;
+    private filePath;
+    private fileCreated;
+    private lastUuid;
+    private entryCount;
+    private createdAt;
+    private lastActivityAt;
+    private currentState;
+    private writeBuffer;
+    private flushTimer;
+    private closed;
+    constructor(sessionDir?: string);
+    /**
+     * Start a new session. Returns the sessionId (UUID).
+     * File is NOT created until the first append (lazy creation).
+     */
+    startSession(): string;
+    /**
+     * Append an entry to the session log.
+     * Assigns a uuid, links parentUuid to the previous entry,
+     * and writes a JSON line to the file.
+     *
+     * First write uses appendFileSync for write-ahead guarantee.
+     * Subsequent writes are batched for up to 100ms before flushing.
+     *
+     * Returns the assigned uuid.
+     */
+    append(entry: SessionEntryInput): string;
+    /**
+     * Force sync any buffered writes to disk immediately.
+     */
+    flush(): void;
+    /**
+     * Returns metadata about the current session.
+     */
+    getMetadata(): SessionMetadata;
+    /**
+     * Returns the current session ID, or null if no session is active.
+     */
+    getSessionId(): string | null;
+    /**
+     * Flush pending writes and mark the session as complete.
+     */
+    close(): void;
+    /**
+     * Returns the file path for the current session, or null.
+     * Exposed for testing and resume integration.
+     */
+    getFilePath(): string | null;
+    private ensureDirectory;
+    private scheduleBatchFlush;
+}
+//# sourceMappingURL=session-store.d.ts.map

package/dist/mcp/services/session-store.js

@@ -0,0 +1,163 @@
+/**
+ * Agentic QE v3 - Append-Only JSONL Session Store
+ *
+ * IMP-04: Transcript-First Session Durability
+ * Provides an append-only JSONL log of all tool calls, results, and state
+ * changes within a session. Supports write batching (100ms window) and
+ * lazy file creation (no file until first append).
+ *
+ * @module mcp/services/session-store
+ */
+import { randomUUID } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+// ============================================================================
+// Session Store
+// ============================================================================
+const DEFAULT_SESSION_DIR = '.agentic-qe/sessions';
+const BATCH_FLUSH_MS = 100;
+export class SessionStore {
+    sessionDir;
+    sessionId = null;
+    filePath = null;
+    fileCreated = false;
+    lastUuid = null;
+    entryCount = 0;
+    createdAt = 0;
+    lastActivityAt = 0;
+    currentState = 'idle';
+    writeBuffer = [];
+    flushTimer = null;
+    closed = false;
+    constructor(sessionDir) {
+        this.sessionDir = sessionDir ?? DEFAULT_SESSION_DIR;
+    }
+    /**
+     * Start a new session. Returns the sessionId (UUID).
+     * File is NOT created until the first append (lazy creation).
+     */
+    startSession() {
+        if (this.sessionId !== null) {
+            this.close();
+        }
+        this.sessionId = randomUUID();
+        this.filePath = path.join(this.sessionDir, `${this.sessionId}.jsonl`);
+        this.fileCreated = false;
+        this.lastUuid = null;
+        this.entryCount = 0;
+        this.createdAt = Date.now();
+        this.lastActivityAt = this.createdAt;
+        this.currentState = 'idle';
+        this.writeBuffer = [];
+        this.flushTimer = null;
+        this.closed = false;
+        return this.sessionId;
+    }
+    /**
+     * Append an entry to the session log.
+     * Assigns a uuid, links parentUuid to the previous entry,
+     * and writes a JSON line to the file.
+     *
+     * First write uses appendFileSync for write-ahead guarantee.
+     * Subsequent writes are batched for up to 100ms before flushing.
+     *
+     * Returns the assigned uuid.
+     */
+    append(entry) {
+        if (!this.sessionId || this.closed) {
+            throw new Error('No active session. Call startSession() first.');
+        }
+        const uuid = randomUUID();
+        const fullEntry = {
+            ...entry,
+            uuid,
+            parentUuid: this.lastUuid,
+        };
+        this.lastUuid = uuid;
+        this.entryCount++;
+        this.lastActivityAt = fullEntry.timestamp;
+        this.currentState = fullEntry.state;
+        const line = JSON.stringify(fullEntry) + '\n';
+        if (!this.fileCreated) {
+            // First write: synchronous for write-ahead guarantee
+            this.ensureDirectory();
+            fs.appendFileSync(this.filePath, line, 'utf-8');
+            this.fileCreated = true;
+        }
+        else {
+            // Subsequent writes: buffer and batch
+            this.writeBuffer.push(line);
+            this.scheduleBatchFlush();
+        }
+        return uuid;
+    }
+    /**
+     * Force sync any buffered writes to disk immediately.
+     */
+    flush() {
+        if (this.flushTimer !== null) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (this.writeBuffer.length > 0 && this.filePath && this.fileCreated) {
+            const batch = this.writeBuffer.join('');
+            this.writeBuffer = [];
+            fs.appendFileSync(this.filePath, batch, 'utf-8');
+        }
+    }
+    /**
+     * Returns metadata about the current session.
+     */
+    getMetadata() {
+        if (!this.sessionId) {
+            throw new Error('No active session. Call startSession() first.');
+        }
+        return {
+            sessionId: this.sessionId,
+            createdAt: this.createdAt,
+            lastActivityAt: this.lastActivityAt,
+            entryCount: this.entryCount,
+            state: this.currentState,
+        };
+    }
+    /**
+     * Returns the current session ID, or null if no session is active.
+     */
+    getSessionId() {
+        return this.sessionId;
+    }
+    /**
+     * Flush pending writes and mark the session as complete.
+     */
+    close() {
+        if (this.closed)
+            return;
+        this.flush();
+        this.closed = true;
+    }
+    /**
+     * Returns the file path for the current session, or null.
+     * Exposed for testing and resume integration.
+     */
+    getFilePath() {
+        return this.filePath;
+    }
+    // --------------------------------------------------------------------------
+    // Private helpers
+    // --------------------------------------------------------------------------
+    ensureDirectory() {
+        const dir = path.dirname(this.filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+    }
+    scheduleBatchFlush() {
+        if (this.flushTimer === null) {
+            this.flushTimer = setTimeout(() => {
+                this.flushTimer = null;
+                this.flush();
+            }, BATCH_FLUSH_MS);
+        }
+    }
+}
+//# sourceMappingURL=session-store.js.map

package/dist/mcp/tool-registry.d.ts

@@ -90,6 +90,15 @@ export declare class ToolRegistry {
      * Clear all tools
      */
     clear(): void;
+    /**
+     * IMP-02: Invoke multiple tools with concurrency partitioning.
+     * Concurrent-safe tools (isConcurrencySafe: true) run in parallel batches.
+     * Non-safe tools run sequentially between batches.
+     */
+    invokeBatch(calls: Array<{
+        name: string;
+        params: Record<string, unknown>;
+    }>): Promise<Array<ToolResult<unknown>>>;
     /**
      * Create result metadata
      */

package/dist/mcp/tool-registry.js

@@ -8,6 +8,8 @@ import { v4 as uuidv4 } from 'uuid';
 import { ALL_DOMAINS } from '../shared/types';
 import { sanitizeInput } from './security/cve-prevention';
 import { toErrorMessage } from '../shared/error-utils.js';
+import { BatchToolExecutor } from './middleware/batch-executor';
+import { withRetry, isRetryableError } from '../shared/retry-engine';
 // ============================================================================
 // Security: Input Validation (SEC-001 Fix)
 // ============================================================================
@@ -363,12 +365,21 @@ export class ToolRegistry {
         tool.lastUsed = new Date();
         this.stats.invocations++;
         try {
-            const result = await tool.handler(sanitizedParams);
+            // IMP-03: Wrap tool handler with unified retry engine
+            const retryResult = await withRetry(() => tool.handler(sanitizedParams), {
+                maxAttempts: 3,
+                baseDelayMs: 500,
+                maxDelayMs: 4000,
+                jitterFraction: 0.25,
+                retryableErrors: isRetryableError,
+            });
+            const result = retryResult.result;
             return {
                 ...result,
                 metadata: {
                     ...result.metadata,
                     ...this.createMetadata(startTime, requestId, tool.definition.domain),
+                    ...(retryResult.attempts > 1 ? { retryAttempts: retryResult.attempts } : {}),
                 },
             };
         }
@@ -463,6 +474,24 @@ export class ToolRegistry {
             errors: 0,
         };
     }
+    /**
+     * IMP-02: Invoke multiple tools with concurrency partitioning.
+     * Concurrent-safe tools (isConcurrencySafe: true) run in parallel batches.
+     * Non-safe tools run sequentially between batches.
+     */
+    async invokeBatch(calls) {
+        const batchCalls = calls.map(call => {
+            const tool = this.tools.get(call.name);
+            return {
+                name: call.name,
+                handler: () => this.invoke(call.name, call.params),
+                isConcurrencySafe: tool?.definition.isConcurrencySafe ?? false,
+            };
+        });
+        const executor = new BatchToolExecutor();
+        const batchResult = await executor.executeBatch(batchCalls);
+        return batchResult.results;
+    }
     /**
      * Create result metadata
      */

package/dist/mcp/types.d.ts

@@ -25,6 +25,7 @@ export interface ToolDefinition {
     category: ToolCategory;
     domain?: DomainName;
     lazyLoad?: boolean;
+    isConcurrencySafe?: boolean;
 }
 /**
  * Tool categories for organization and lazy loading

package/dist/plugins/cache.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Agentic QE v3 - Plugin Cache (IMP-09)
+ *
+ * Versioned immutable cache for installed plugins.
+ * Stores plugins at `.agentic-qe/plugins/{name}@{version}/`.
+ * Once cached, a version is never modified — only new versions are added.
+ */
+import type { QEPluginManifest } from './manifest';
+export interface CachedPlugin {
+    manifest: QEPluginManifest;
+    path: string;
+    cachedAt: string;
+}
+export interface PluginCacheOptions {
+    /** Base directory for the plugin cache (default: .agentic-qe/plugins) */
+    cacheDir?: string;
+    /** Number of old versions to keep per plugin (default: 2) */
+    keepVersions?: number;
+}
+export declare class PluginCache {
+    private readonly cacheDir;
+    private readonly keepVersions;
+    constructor(options?: PluginCacheOptions);
+    /** Check if a specific version is cached. */
+    has(name: string, version: string): boolean;
+    /** Get the cached path for a plugin version, or undefined if not cached. */
+    get(name: string, version: string): CachedPlugin | undefined;
+    /**
+     * Store a plugin in the cache by copying from a source directory.
+     * Returns the cache path. If already cached, returns the existing path
+     * (immutable — no overwrite).
+     */
+    store(manifest: QEPluginManifest, sourceDir: string): string;
+    /** Remove a specific cached version. */
+    remove(name: string, version: string): boolean;
+    /** List all cached versions for a plugin. */
+    listVersions(name: string): CachedPlugin[];
+    /** List all cached plugins (latest version of each). */
+    listAll(): CachedPlugin[];
+    private versionDir;
+    private pruneOldVersions;
+    private copyDir;
+}
+//# sourceMappingURL=cache.d.ts.map